blob: fbe427800dcf3a2c63a9bf288bca74b837678f4d [file] [log] [blame]
<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Documentation Concept &mdash; OpenPASS Documentation</title>
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../_static/css/custom.css" type="text/css" />
<link rel="stylesheet" href="../_static/tabs.css" type="text/css" />
<link rel="shortcut icon" href="../_static/openPASS.ico"/>
<!--[if lt IE 9]>
<script src="../_static/js/html5shiv.min.js"></script>
<![endif]-->
<script data-url_root="../" id="documentation_options" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="External Dependencies" href="../other_information/10_external_dependencies.html" />
<link rel="prev" title="Working with Visual Studio Code" href="ide_support/30_vscode.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../index.html" class="icon icon-home"> openPASS
<img src="../_static/openPASS.png" class="logo" alt="Logo"/>
</a>
<div class="version">
9999.9999.9999
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Installation Guide</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../installation_guide/10_getting_started.html">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="../installation_guide/20_install_prerequisites.html">Installing Prerequisites</a></li>
<li class="toctree-l1"><a class="reference internal" href="../installation_guide/30_install_openpass.html">Installing OpenPASS</a></li>
<li class="toctree-l1"><a class="reference internal" href="../installation_guide/50_further_guidance.html">Further Guidance</a></li>
<li class="toctree-l1"><a class="reference internal" href="../installation_guide/60_conan.html">Building with Conan</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">User Guides</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../user_guide/10_overview.html">Overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user_guide/20_tutorials.html">Tutorials</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user_guide/30_gui_plugins.html">GUI Plugins</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user_guide/40_configs_in_depth.html">Configs in Depth</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user_guide/50_outputs_in_depth.html">Outputs in Depth</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user_guide/60_scenario_simulation.html">Simulator</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Advanced topics</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../advanced_topics/20_simulator_advanced.html">Simulator</a></li>
<li class="toctree-l1"><a class="reference internal" href="../advanced_topics/30_testing.html">EndToEnd Test Framework</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Developer Information</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="10_ide_support.html">IDE Support</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Documentation Concept</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#basic-build-mechanics">Basic Build Mechanics</a></li>
<li class="toctree-l2"><a class="reference internal" href="#openpass-as-submodule">openPASS as Submodule</a></li>
</ul>
</li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Other Information</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../other_information/10_external_dependencies.html">External Dependencies</a></li>
<li class="toctree-l1"><a class="reference internal" href="../other_information/20_glossary.html">Glossary</a></li>
<li class="toctree-l1"><a class="reference internal" href="../other_information/30_license.html">License</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">openPASS</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home"></a> &raquo;</li>
<li>Documentation Concept</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/developer_information/20_documentation.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="documentation-concept">
<span id="documentation"></span><h1>Documentation Concept<a class="headerlink" href="#documentation-concept" title="Permalink to this headline"></a></h1>
<p><strong>OpenPASS</strong> (Open Source) is developed under the Eclipse Public License and as such private and commercial use is allowed under certain rules (see <a class="reference external" href="https://www.eclipse.org/legal/epl-2.0/">EPL 2.0</a>).
The basic documentation concept facilitates this by providing a way to include custom content which is not necessarily part of the <strong>openPASS</strong> (Open Source) distribution.
This results in certain restrictions on how documentation is to be written.
The following sections describe this restrictions and the process of integrating proprietary documentation into the <strong>openPASS</strong> (Open Source) documentation build.</p>
<div class="section" id="basic-build-mechanics">
<h2>Basic Build Mechanics<a class="headerlink" href="#basic-build-mechanics" title="Permalink to this headline"></a></h2>
<p>The required steps to build the documentation are described in <a class="reference internal" href="../installation_guide/30_install_openpass.html#download-and-install-openpass"><span class="std std-ref">Installing OpenPASS</span></a>, provided by CMake files using the build option <code class="docutils literal notranslate"><span class="pre">WITH_GUI=ON</span></code>.
Before building, a temporary copy of the original documentation is made.
This temporary copy acts as <em>seam</em> for custom extension, as proprietary content is simply copied into the temporary folder (see below).
This mechanism keeps contents clearly separated during development and allows easy transition from closed to open source if desired.</p>
<p>References to files located outside of the documentation root is used at various places, as this allows to keep documentation as close to the source as possible.
These references normally would become invalid when the documentation source is copied or moved to another location.
Thus, placeholders are used to have a fixed reference to the <strong>openPASS</strong> (Open Source) tree:</p>
<blockquote>
<div><ul class="simple">
<li><p><em>&#64;</em><em>OP_REL_ROOT</em><em>&#64;</em> - Root of repository (<code class="docutils literal notranslate"><span class="pre">.</span></code>)</p></li>
<li><p><em>&#64;</em><em>OP_REL_GUI</em><em>&#64;</em> - Folder <code class="docutils literal notranslate"><span class="pre">./gui</span></code></p></li>
<li><p><em>&#64;</em><em>OP_REL_SIM</em><em>&#64;</em> - Folder <code class="docutils literal notranslate"><span class="pre">./sim</span></code></p></li>
</ul>
</div></blockquote>
<p>This placeholders must be used when files outside of the documentation root shall be referenced.
Note that this also makes sources more readable.</p>
<p><strong>Example</strong></p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">..</span> <span class="n">literalinclude</span><span class="p">::</span> <span class="nd">@OP_REL_SIM</span><span class="o">@/</span><span class="n">contrib</span><span class="o">/</span><span class="n">examples</span><span class="o">/</span><span class="n">Common</span><span class="o">/</span><span class="n">SceneryConfiguration</span><span class="o">.</span><span class="n">xodr</span>
</pre></div>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Generally, when moving or deleting files, make sure to run <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">clean</span></code> prior to <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">doc</span></code> to remove any outdated files from the build directory.</p>
</div>
</div>
<div class="section" id="openpass-as-submodule">
<h2>openPASS as Submodule<a class="headerlink" href="#openpass-as-submodule" title="Permalink to this headline"></a></h2>
<ol class="arabic">
<li><p><strong>Write the documentation</strong></p>
<p>As custom documentation simply integrates into the <strong>openPASS</strong> (Open Source) documentation, it is also written in the <em>reStructuredText</em> file format.
Thereby files have to reside in a directory structure that is a clone of the open source documentation directory structure (starting from <code class="docutils literal notranslate"><span class="pre">doc/source</span></code>).
During the build your documentation and the open source documentation will both be copied to a temporary directory.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Files existing in both source directories will be overwritten at the destination, with the custom files having higher precedence.</p>
</div>
<p>On the TOC tree level, the <strong>seam</strong> to custom files is made through <em>globbing</em> using wildcards, such as <code class="docutils literal notranslate"><span class="pre">folder/*.rst</span></code>.
Ordering of the files (and to avoid file name collisions) is established through a two digit number prefix and an underscore, e.g. <code class="docutils literal notranslate"><span class="pre">10_quickstart.rst</span></code>.
This allows injection of proprietary documentation at any position in the TOC tree, as the order of headings is determined by the (ASCII) sorting of the filenames.</p>
</li>
<li><p><strong>Referencing files</strong></p>
<p>Sphinx uses some special path format when referencing files from documentation.
All paths are relative to a single documentation root directory, but are specified like absolute paths (i.e. with a leading slash).
Due to the documentation source files being copied to a temporary directory during build, all file references have to be prefixed with a path constant:</p>
<ul class="simple">
<li><p>When specifying a file reference relative to the <strong>openPASS</strong> (Open Source) repository, the file path has to be prefixed with custom placeholders, such as <em>&#64;</em><em>OP_REL_ROOT</em><em>&#64;</em> (see above).</p></li>
<li><p>When referencing files relative to a custom root, additional placeholders can be introduced in a custom <code class="docutils literal notranslate"><span class="pre">PrepareDocCustom.cmake</span></code> (see next steps).</p></li>
<li><p>These placeholders will then coexist and will be replaced with the corresponding paths during build.</p></li>
</ul>
</li>
<li><p><strong>Add a cmake file for documentation preparation</strong></p>
<p>The file <a class="reference download internal" download="" href="../_downloads/13db75188596730e5b909e7eb9b658b0/PrepareDocCustom.cmake"><code class="xref download docutils literal notranslate"><span class="pre">PrepareDocCustom.cmake</span></code></a> can be used as a template.
Just add the placeholders used in your proprietary documentation.</p>
<p>This diff highlights the important parts in comparison to the original <code class="docutils literal notranslate"><span class="pre">PrepareDoc.cmake</span></code>, used in the open source documentation build:</p>
<div class="highlight-udiff notranslate"><div class="highlight"><pre><span></span><span class="gd">--- C:/Arbeit/050_PASS/eclipse/doc/PrepareDoc.cmake</span>
<span class="gi">+++ C:/Arbeit/050_PASS/eclipse/build/doc/source/developer_information/_static/custom_doc/PrepareDocCustom.cmake</span>
<span class="gu">@@ -20,6 +20,7 @@</span>
# - @OP_REL_ROOT@ =&gt; relative path to root of the openpass repository
# - @OP_REL_GUI@ =&gt; resolves to @OP_REL_ROOT@/gui
# - @OP_REL_SIM@ =&gt; resolves to @OP_REL_ROOT@/sim
<span class="gi">+# - @CUSTOM_REL_SIM@ =&gt; relative path to the &quot;custom&quot; root (.)</span>
macro(copy_documentation source destination)
message(VERBOSE &quot;Copy ${source} to ${destination}&quot;)
<span class="gu">@@ -34,9 +35,10 @@</span>
string(REGEX REPLACE &quot;(.*)/$&quot; &quot;\\1&quot; target ${target})
# Placeholder for conf.py: no initial &#39;/&#39; =&gt; real relative paths
<span class="gd">- set(OP_REL_ROOT ../${target}) # relative path to repository root</span>
<span class="gi">+ set(OP_REL_ROOT ../${target}/deps/os) # relative path to the openPASS open source code, with prefix &#39;../${target}&#39; pointing to the custom repository root if this file is located at &lt;root&gt;/doc</span>
set(OP_REL_GUI ${OP_REL_ROOT}/gui) # relative path to gui root
set(OP_REL_SIM ${OP_REL_ROOT}/sim) # relative path to simulation root
<span class="gi">+ set(CUSTOM_REL_SIM ../${target}) # relative path to the custom repository root (here, equal to custom sim root)</span>
configure_file(${destination}/source/conf.py
${destination}/source/conf.py @ONLY)
<span class="gu">@@ -46,6 +48,7 @@</span>
set(OP_REL_ROOT /${OP_REL_ROOT})
set(OP_REL_GUI /${OP_REL_GUI})
set(OP_REL_SIM /${OP_REL_SIM})
<span class="gi">+ set(CUSTOM_REL_SIM /${CUSTOM_REL_SIM})</span>
file(GLOB_RECURSE rstFiles LIST_DIRECTORIES false ${destination}/*.rst)
</pre></div>
</div>
</li>
<li><p><strong>Add a ``doc`` CMake target to your custom build</strong></p>
<p>To add your custom build target, the following <code class="docutils literal notranslate"><span class="pre">CMakeLists.txt</span></code> snippet can be used as template.
Note the usage of the <code class="docutils literal notranslate"><span class="pre">PrepareDocCustom.cmake</span></code>.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>################################################################################
# Copyright (c) 2021 in-tech GmbH
#
# This program and the accompanying materials are made available under the
# terms of the Eclipse Public License 2.0 which is available at
# http://www.eclipse.org/legal/epl-2.0.
#
# SPDX-License-Identifier: EPL-2.0
################################################################################
if(WITH_DOC)
add_custom_target(doc
# Copy documentation and change placeholders
# (see PrepareDoc for more information)
COMMAND ${CMAKE_COMMAND}
-DSRC=${OPENPASS_OS_DIR}/doc/source
-DDST=${CMAKE_BINARY_DIR}/doc
-P ${OPENPASS_OS_DIR}/doc/PrepareDoc.cmake
COMMENT &quot;Copy OS documentation and replace placeholders&quot;
COMMAND ${CMAKE_COMMAND}
-DSRC=${CMAKE_CURRENT_LIST_DIR}/source
-DDST=${CMAKE_BINARY_DIR}/doc
<span class="hll"> -P ${CMAKE_CURRENT_LIST_DIR}/PrepareDocCustom.cmake
</span> COMMENT &quot;Copy custom documentation and replace placeholders (overrides!)&quot;
COMMAND ${SPHINX_EXECUTABLE} # sphinx-build
-M html # generate HTML
${CMAKE_BINARY_DIR}/doc/source # source path
${CMAKE_BINARY_DIR}/doc # destination path
-DWITH_API_DOC=${WITH_API_DOC} # turn exhale ON/OFF
COMMENT &quot;Build sphinx documentation&quot;
COMMAND ${CMAKE_COMMAND}
-E cmake_echo_color --green
&quot;The HTML pages are in ${CMAKE_BINARY_DIR}/doc/html.&quot;)
set_property(DIRECTORY APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES
${CMAKE_BINARY_DIR}/doc)
# make HTML doc available on install
install(DIRECTORY ${CMAKE_BINARY_DIR}/doc/html/
DESTINATION ${CMAKE_INSTALL_PREFIX}/doc)
endif()
</pre></div>
</div>
</li>
<li><p><strong>Provide a config file for Sphinx</strong></p>
<p>Sphinx allows to specify a configuration residing in <code class="docutils literal notranslate"><span class="pre">conf.py</span></code> in the documentation source directory.
Customization is done by providing a customized file here, with the open source version as template (<a class="reference download internal" download="" href="../_downloads/7444bd1ca59fbbe265e05baad670d963/conf.py"><code class="xref download docutils literal notranslate"><span class="pre">/../../../doc/source/conf.py</span></code></a>).</p>
</li>
</ol>
</div>
</div>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="ide_support/30_vscode.html" class="btn btn-neutral float-left" title="Working with Visual Studio Code" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="../other_information/10_external_dependencies.html" class="btn btn-neutral float-right" title="External Dependencies" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2021 OpenPASS Working Group.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>