content/html/advanced_topics/10_documentation.html - www.eclipse.org/simopenpass - Git at Google



 <!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/css/theme.css" type="text/css" />
   <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
   <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/tabs.css" type="text/css" />
   <link rel="stylesheet" href="../_static/css/custom.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 type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
         <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 type="text/javascript" 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="Simulator" href="20_simulator_advanced.html" />
     <link rel="prev" title="Basic Example" href="../user_guide/sim_user_guide/examples/basic.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="main navigation">


               <p class="caption"><span class="caption-text">Installation Guides</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="../installation_guide/10_gui_installation_guide.html">GUI Installation Guide</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../installation_guide/20_sim_installation_guide.html">Simulation Installation Guide</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../installation_guide/21_pcm_installation_guide.html">PCM Installation Guide</a></li>
 </ul>
 <p class="caption"><span class="caption-text">User Guides</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="../user_guide/10_gui_user_guide.html">GUI User Guide</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../user_guide/20_sim_user_guide.html">Simulation User Guide</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Advanced topics</span></p>
 <ul class="current">
 <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="#adding-custom-content">Adding Custom Content</a></li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="20_simulator_advanced.html">Simulator</a></li>
 </ul>
 <p class="caption"><span class="caption-text">Other Information</span></p>
 <ul>
 <li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
 <li class="toctree-l1"><a class="reference internal" href="../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="top navigation">

           <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="breadcrumbs 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/advanced_topics/10_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/sim_installation_guide/meta/sphinx.html#sphinx"><span class="std std-ref">Sphinx</span></a>, provided by CMake files.
 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, a placeholder is used to have a fixed reference to the <strong>openPASS</strong> (Open Source) tree: <em>&#64;</em><em>OP_REL_SIM</em><em>&#64;</em>.
 This placeholder must be used when referencing files outside of the documentation root.
 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">DefaultConfigurations</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="adding-custom-content">
 <h2>Adding Custom Content<a class="headerlink" href="#adding-custom-content" 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">sim/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 well-known path constant:</p>
 <ul class="simple">
 <li><p>When specifying a file reference to the <strong>openPASS</strong> (Open Source) repository, the file path has to be prefixed with <em>&#64;</em><em>OP_REL_SIM</em><em>&#64;</em>.</p></li>
 <li><p>When referencing files relative to a custom root, an additional placeholder 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 by the correct 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/2e14f979ef821e72b19423c7a3fd9e5d/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">--- /home/cloud/simopenpass/sim/doc/PrepareDoc.cmake</span>
 <span class="gi">+++ /home/cloud/simopenpass/sim/doc/source/advanced_topics/_static/custom_doc/PrepareDocCustom.cmake</span>
 <span class="gu">@@ -20,6 +20,7 @@</span>
  # - @OP_REL_SIM@ =&gt; relative path to the &quot;op sim&quot; root (e.g. deps/os/sim if
  #   using a git submodule with the openPASS open source code at deps/os inside
  #   the local repository)
 <span class="gi">+# - @CUSTOM_REL_SIM@ =&gt; relative path to the &quot;custom sim&quot; root (.)</span>

  macro(copy_documentation source destination)
      message(VERBOSE &quot;Copy ${source} to ${destination}&quot;)
 <span class="gu">@@ -34,7 +35,8 @@</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_SIM ../${target})   # relative path to the openPASS open source code</span>
 <span class="gi">+    set(OP_REL_SIM ../${target}/deps/os/sim)   # 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>
 <span class="gi">+    set(CUSTOM_REL_SIM ../${target})           # relative path to the custom repository root (equal to custom sim root in this example)</span>

      configure_file(${destination}/source/conf.py
                     ${destination}/source/conf.py @ONLY)
 <span class="gu">@@ -42,6 +44,7 @@</span>
      # Placeholder for RST files: use initial &#39;/&#39; =&gt; sphinx style for &quot;from source&quot;
      # Override old one, because we want to use the same placeholder in both contexts
      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 https://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}/sim/doc/source
           -DDST=${CMAKE_BINARY_DIR}/doc
           -P ${OPENPASS_OS_DIR}/sim/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/9b97e1145820436cecdf63c39b46a777/conf.py"><code class="xref download docutils literal notranslate"><span class="pre">conf.py</span></code></a>).</p>
 </li>
 </ol>
 </div>
 </div>


            </div>

           </div>
           <footer>
     <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
         <a href="20_simulator_advanced.html" class="btn btn-neutral float-right" title="Simulator" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
         <a href="../user_guide/sim_user_guide/examples/basic.html" class="btn btn-neutral float-left" title="Basic Example" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</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 type="text/javascript">
       jQuery(function () {
           SphinxRtdTheme.Navigation.enable(true);
       });
   </script>


 </body>
 </html>


	<!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/css/theme.css" type="text/css" />
	<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
	<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/tabs.css" type="text/css" />
	<link rel="stylesheet" href="../_static/css/custom.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 type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
	<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 type="text/javascript" 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="Simulator" href="20_simulator_advanced.html" />
	<link rel="prev" title="Basic Example" href="../user_guide/sim_user_guide/examples/basic.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="main navigation">






	<p class="caption"><span class="caption-text">Installation Guides</span></p>
	<ul>
	<li class="toctree-l1"><a class="reference internal" href="../installation_guide/10_gui_installation_guide.html">GUI Installation Guide</a></li>
	<li class="toctree-l1"><a class="reference internal" href="../installation_guide/20_sim_installation_guide.html">Simulation Installation Guide</a></li>
	<li class="toctree-l1"><a class="reference internal" href="../installation_guide/21_pcm_installation_guide.html">PCM Installation Guide</a></li>
	</ul>
	<p class="caption"><span class="caption-text">User Guides</span></p>
	<ul>
	<li class="toctree-l1"><a class="reference internal" href="../user_guide/10_gui_user_guide.html">GUI User Guide</a></li>
	<li class="toctree-l1"><a class="reference internal" href="../user_guide/20_sim_user_guide.html">Simulation User Guide</a></li>
	</ul>
	<p class="caption"><span class="caption-text">Advanced topics</span></p>
	<ul class="current">
	<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="#adding-custom-content">Adding Custom Content</a></li>
	</ul>
	</li>
	<li class="toctree-l1"><a class="reference internal" href="20_simulator_advanced.html">Simulator</a></li>
	</ul>
	<p class="caption"><span class="caption-text">Other Information</span></p>
	<ul>
	<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
	<li class="toctree-l1"><a class="reference internal" href="../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="top navigation">

	<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="breadcrumbs 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/advanced_topics/10_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/sim_installation_guide/meta/sphinx.html#sphinx"><span class="std std-ref">Sphinx</span></a>, provided by CMake files.
	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, a placeholder is used to have a fixed reference to the <strong>openPASS</strong> (Open Source) tree: <em>@</em><em>OP_REL_SIM</em><em>@</em>.
	This placeholder must be used when referencing files outside of the documentation root.
	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">DefaultConfigurations</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="adding-custom-content">
	<h2>Adding Custom Content<a class="headerlink" href="#adding-custom-content" 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">sim/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 well-known path constant:</p>
	<ul class="simple">
	<li><p>When specifying a file reference to the <strong>openPASS</strong> (Open Source) repository, the file path has to be prefixed with <em>@</em><em>OP_REL_SIM</em><em>@</em>.</p></li>
	<li><p>When referencing files relative to a custom root, an additional placeholder 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 by the correct 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/2e14f979ef821e72b19423c7a3fd9e5d/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">--- /home/cloud/simopenpass/sim/doc/PrepareDoc.cmake</span>
	<span class="gi">+++ /home/cloud/simopenpass/sim/doc/source/advanced_topics/_static/custom_doc/PrepareDocCustom.cmake</span>
	<span class="gu">@@ -20,6 +20,7 @@</span>
	# - @OP_REL_SIM@ => relative path to the "op sim" root (e.g. deps/os/sim if
	# using a git submodule with the openPASS open source code at deps/os inside
	# the local repository)
	<span class="gi">+# - @CUSTOM_REL_SIM@ => relative path to the "custom sim" root (.)</span>

	macro(copy_documentation source destination)
	message(VERBOSE "Copy ${source} to ${destination}")
	<span class="gu">@@ -34,7 +35,8 @@</span>
	string(REGEX REPLACE "(.*)/$" "\\1" target ${target})

	# Placeholder for conf.py: no initial '/' => real relative paths
	<span class="gd">- set(OP_REL_SIM ../${target}) # relative path to the openPASS open source code</span>
	<span class="gi">+ set(OP_REL_SIM ../${target}/deps/os/sim) # 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>
	<span class="gi">+ set(CUSTOM_REL_SIM ../${target}) # relative path to the custom repository root (equal to custom sim root in this example)</span>

	configure_file(${destination}/source/conf.py
	${destination}/source/conf.py @ONLY)
	<span class="gu">@@ -42,6 +44,7 @@</span>
	# Placeholder for RST files: use initial '/' => sphinx style for "from source"
	# Override old one, because we want to use the same placeholder in both contexts
	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 https://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}/sim/doc/source
	-DDST=${CMAKE_BINARY_DIR}/doc
	-P ${OPENPASS_OS_DIR}/sim/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/9b97e1145820436cecdf63c39b46a777/conf.py"><code class="xref download docutils literal notranslate"><span class="pre">conf.py</span></code></a>).</p>
	</li>
	</ol>
	</div>
	</div>


	</div>

	</div>
	<footer>
	<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
	<a href="20_simulator_advanced.html" class="btn btn-neutral float-right" title="Simulator" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
	<a href="../user_guide/sim_user_guide/examples/basic.html" class="btn btn-neutral float-left" title="Basic Example" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</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 type="text/javascript">
	jQuery(function () {
	SphinxRtdTheme.Navigation.enable(true);
	});
	</script>






	</body>
	</html>