<!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 — 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> »</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>@</em><em>OP_REL_ROOT</em><em>@</em> - Root of repository (<code class="docutils literal notranslate"><span class="pre">.</span></code>)</p></li> | |
<li><p><em>@</em><em>OP_REL_GUI</em><em>@</em> - Folder <code class="docutils literal notranslate"><span class="pre">./gui</span></code></p></li> | |
<li><p><em>@</em><em>OP_REL_SIM</em><em>@</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>@</em><em>OP_REL_ROOT</em><em>@</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@ => relative path to root of the openpass repository | |
# - @OP_REL_GUI@ => resolves to @OP_REL_ROOT@/gui | |
# - @OP_REL_SIM@ => resolves to @OP_REL_ROOT@/sim | |
<span class="gi">+# - @CUSTOM_REL_SIM@ => relative path to the "custom" root (.)</span> | |
macro(copy_documentation source destination) | |
message(VERBOSE "Copy ${source} to ${destination}") | |
<span class="gu">@@ -34,9 +35,10 @@</span> | |
string(REGEX REPLACE "(.*)/$" "\\1" target ${target}) | |
# Placeholder for conf.py: no initial '/' => 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 '../${target}' pointing to the custom repository root if this file is located at <root>/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 "Copy OS documentation and replace placeholders" | |
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 "Copy custom documentation and replace placeholders (overrides!)" | |
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 "Build sphinx documentation" | |
COMMAND ${CMAKE_COMMAND} | |
-E cmake_echo_color --green | |
"The HTML pages are in ${CMAKE_BINARY_DIR}/doc/html.") | |
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>© 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> |