Documentation Concept¶

openPASS (Open Source) is developed under the Eclipse Public License and as such private and commercial use is allowed under certain rules (see EPL 2.0). The basic documentation concept facilitates this by providing a way to include custom content which is not necessarily part of the openPASS (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 openPASS (Open Source) documentation build.

Basic Build Mechanics¶

The required steps to build the documentation are described in Installing openPASS. Before building, a temporary copy of the original documentation is made. This temporary copy acts as seam 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.

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 openPASS (Open Source) tree:

@OP_REL_ROOT@ - Root of repository (.)

@OP_REL_SIM@ - Folder ./sim

These placeholders must be used when files outside of the documentation root shall be referenced. Note that this also makes sources more readable.

Example

.. literalinclude:: @OP_REL_SIM@/contrib/examples/Common/SceneryConfiguration.xodr

Warning

Generally, when moving or deleting files, make sure to run make clean prior to make doc to remove any outdated files from the build directory.

openPASS as Submodule¶

Write the documentation

As custom documentation simply integrates into the openPASS (Open Source) documentation, it is also written in the reStructuredText file format. Thereby files have to reside in a directory structure that is a clone of the open source documentation directory structure (starting from doc/source). During the build your documentation and the open source documentation will both be copied to a temporary directory.

Note

Files existing in both source directories will be overwritten at the destination, with the custom files having higher precedence.

On the TOC tree level, the seam to custom files is made through globbing using wildcards, such as folder/*.rst. Ordering of the files (and to avoid file name collisions) is established through a two digit number prefix and an underscore, e.g. 10_quickstart.rst. 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.
Referencing files

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:
- When specifying a file reference relative to the openPASS (Open Source) repository, the file path has to be prefixed with custom placeholders, such as @OP_REL_ROOT@ (see above).
- When referencing files relative to a custom root, additional placeholders can be introduced in a custom PrepareDocCustom.cmake (see next steps).
- These placeholders will then coexist and will be replaced with the corresponding paths during build.

Add a cmake file for documentation preparation

The file PrepareDocCustom.cmake can be used as a template. Just add the placeholders used in your proprietary documentation.

This diff highlights the important parts in comparison to the original PrepareDoc.cmake, used in the open source documentation build:

--- W:/repo/doc/PrepareDoc.cmake
+++ W:/build/doc/source/developer_information/_static/custom_doc/PrepareDocCustom.cmake
@@ -19,6 +19,7 @@
 # Currently supported PLACEHOLDERS
 # - @OP_REL_ROOT@ => relative path to root of the openpass repository
 # - @OP_REL_SIM@  => resolves to @OP_REL_ROOT@/sim
+# - @CUSTOM_REL_SIM@ => relative path to the "custom" root (.)
 
 macro(copy_documentation source destination)
     message(VERBOSE "Copy ${source} to ${destination}")
@@ -33,8 +34,9 @@
     string(REGEX REPLACE "(.*)/$" "\\1" target ${target})
 
     # Placeholder for conf.py: no initial '/' => real relative paths
-    set(OP_REL_ROOT ../${target})         # relative path to repository root
+    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
     set(OP_REL_SIM ${OP_REL_ROOT}/sim)    # relative path to simulation root
+    set(CUSTOM_REL_SIM ../${target})      # relative path to the custom repository root (here, equal to custom sim root)
 
     configure_file(${destination}/source/conf.py
                    ${destination}/source/conf.py @ONLY)
@@ -43,6 +45,7 @@
     # Override old one, because we want to use the same placeholder in both contexts
     set(OP_REL_ROOT /${OP_REL_ROOT})
     set(OP_REL_SIM /${OP_REL_SIM})
+    set(CUSTOM_REL_SIM /${CUSTOM_REL_SIM})
 
     file(GLOB_RECURSE rstFiles LIST_DIRECTORIES false ${destination}/*.rst)
 

Add a ``doc`` CMake target to your custom build

To add your custom build target, the following CMakeLists.txt snippet can be used as template. Note the usage of the PrepareDocCustom.cmake.

################################################################################
# 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
          -P ${CMAKE_CURRENT_LIST_DIR}/PrepareDocCustom.cmake
          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()

Provide a config file for Sphinx

Sphinx allows to specify a configuration residing in conf.py in the documentation source directory. Customization is done by providing a customized file here, with the open source version as template (/../../../repo/doc/source/conf.py).

Docker Image¶

This documentation provides an overview of the Dockerfile used to build an image containing all the necessary packages required for building openPASS (Open Source). The resulting image can be used as a development environment.

Usage

Clone the openPASS (Open Source) project
At the root level (the folder containing the repo), execute the following command
```
docker build -f ./repo/utils/Dockerfile -t <DockerImageName> .
```
Note

The Dockerfile assumes the name of the repository as “repo”. The command and the Dockerfile should be modified accordingly, if different name is used