# 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, provided by CMake files using the build option `WITH_GUI=ON`. 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_GUI@ - Folder `./gui`

> - @OP_REL_SIM@ - Folder `./sim`

This 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

1. 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.

2. 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.

3. 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
       @@ -20,6 +20,7 @@
        # - @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
       +# - @CUSTOM_REL_SIM@ => relative path to the "custom" root (.)

        macro(copy_documentation source destination)
            message(VERBOSE "Copy ${source} to ${destination}")
       @@ -34,9 +35,10 @@
            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_GUI ${OP_REL_ROOT}/gui)    # relative path to gui root
            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)
       @@ -46,6 +48,7 @@
            set(OP_REL_ROOT /${OP_REL_ROOT})
            set(OP_REL_GUI /${OP_REL_GUI})
            set(OP_REL_SIM /${OP_REL_SIM})
       +    set(CUSTOM_REL_SIM /${CUSTOM_REL_SIM})

            file(GLOB_RECURSE rstFiles LIST_DIRECTORIES false ${destination}/*.rst)

4. 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()

5. 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`).