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

.. _documentation:

Documentation Concept
=====================

|Op_oss| is developed under the Eclipse Public License and as such private and commercial use is allowed under certain rules (see `EPL 2.0 <https://www.eclipse.org/legal/epl-2.0/>`_).
The basic documentation concept facilitates this by providing a way to include custom content which is not necessarily part of the |op_oss| 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 |op_oss| documentation build.

Basic Build Mechanics
---------------------

The required steps to build the documentation are described in :ref:`sphinx`, provided by CMake files.
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, a placeholder is used to have a fixed reference to the |op_oss| tree: *@*\ *OP_REL_SIM*\ *@*.
This placeholder must be used when referencing files outside of the documentation root.
Note that this also makes sources more readable.

**Example**

.. literalinclude:: /../../../sim/doc/source/user_guide/sim_user_guide/input/scenery.rst
   :start-at: OP_REL_SIM
   :lines: 1

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

Adding Custom Content
---------------------

#. **Write the documentation**

   As custom documentation simply integrates into the |op_oss| 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 ``sim/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 well-known path constant:

   - When specifying a file reference to the |op_oss| repository, the file path has to be prefixed with *@*\ *OP_REL_SIM*\ *@*.
   - When referencing files relative to a custom root, an additional placeholder can be introduced in a custom ``PrepareDocCustom.cmake`` (see next steps).
   - These placeholders will then coexist and will be replaced by the correct paths during build.

#. **Add a cmake file for documentation preparation**

   The file :download:`PrepareDocCustom.cmake<_static/custom_doc/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:

   .. literalinclude:: /../../../sim/doc/source/advanced_topics/_static/custom_doc/PrepareDocCustom.cmake
      :diff: /../../../sim/doc/PrepareDoc.cmake

#. **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``.

   .. literalinclude:: /../../../sim/doc/source/advanced_topics/_static/custom_doc/CMakeLists_doc.cmake
      :emphasize-lines: 23

#. **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 (:download:`conf.py</../../../sim/doc/source/conf.py>`).