Commit 7edded87 authored by Reinhard Biegel's avatar Reinhard Biegel
Browse files

Merge branch '122-updates-to-documentation' into 'develop'

Resolve "Updates to documentation"

See merge request !76
parents 0c65cf1c abf24a99
......@@ -23,3 +23,6 @@ doc/source/api.rst
# third party references
deps/*
# clangd cache
.cache
......@@ -25,7 +25,7 @@ A list of frequently asked questions:
2. __Which traffic signs does openPASS support?__
[Here](https://gitlab.eclipse.org/eclipse/simopenpass/simopenpass/-/blob/servant/sim/doc/DoxyGen/Function/Markdown/Simulation/Development/FrameworkModules.md#L310) is an overview over the supported traffic signs.
[Here](https://gitlab.eclipse.org/eclipse/simopenpass/simopenpass/-/blob/servant/doc/source/advanced_topics/simulator/world_osi.rst#L157) is an overview over the supported traffic signs.
3. __Can openPASS simulate multiple simulation runs in parallel?__
......
......@@ -22,11 +22,13 @@ if(WITH_DOC)
-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
-D api_doc_build=${WITH_API_DOC} # turn exhale ON/OFF
-W --keep-going # treat warnings as errors but keep-going
-n # https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-nitpicky
COMMENT "Build Sphinx documentation"
COMMAND ${CMAKE_COMMAND}
-E cmake_echo_color --green
"The HTML pages are in ${CMAKE_BINARY_DIR}/doc/html.")
"The HTML pages are in ${CMAKE_BINARY_DIR}/doc/html/index.html")
set_property(DIRECTORY APPEND PROPERTY ADDITIONAL_MAKE_CLEAN_FILES
${CMAKE_BINARY_DIR}/doc)
......
......@@ -24,14 +24,54 @@ Sphinx
- [OSI Sphinx Config](https://github.com/OpenSimulationInterface/osi-documentation/blob/master/conf.py)
## Building the documentation
## Building the documentation (Windows)
1. Get MSYS2 from https://www.msys2.org/
2. Start MSYS2 MSYS and update the system packages:
```
pacman -Syuu
```
If the upgrade requires a restart of MSYS2, resume the upgrade by re-opening the shell and call:
```
pacman -Suu
```
3. Install required packages: Start MSYS2 MinGW 64bit and execute
```
pacman -S mingw-w64-x86_64-cmake #Tested with 3.19.2-1
pacman -S make #Tested with 4.3-1
pacman -S mingw-w64-x86_64-gcc #Tested with 10.2.0-6
pacman -S mingw-w64-x86_64-python-sphinx
pacman -S mingw-w64-x86_64-python-pip #Tested with 21.1.3-2
pacman -S mingw-w64-x86_64-python-lxml #Tested with 4.6.2-2
wget -P /mingw64/share/texmf-dist/tex/latex/anyfontsize http://mirrors.ctan.org/macros/latex/contrib/anyfontsize/anyfontsize.sty
pacman -S mingw-w64-x86_64-zziplib #Tested with 0.13.72-3
pacman -S mingw-w64-x86_64-texlive-bin #Tested with 2021.20210424-5
pacman -S mingw-w64-x86_64-texlive-core #Tested with 2021.20210519-2
pacman -S mingw-w64-x86_64-texlive-font-utils #Tested with 2021.20210519-1
pip3 install sphinx-rtd-theme sphinx-tabs
```
4. Create a directory named `build` inside your checked out repository and navigate to it in the MSYS2 MinGW 64bit shell
5. Execute
```
cmake -G "MSYS Makefiles" -DWITH_DOC=ON -DWITH_SIMCORE=OFF -DWITH_TESTS=OFF ..
make doc
```
## Building the documentation (Debian)
```
# install python, pip, spellchecker, ...
sudo apt install doxygen python3 python3-pip dvipng
# install sphinx and its extensions
pip3 install sphinx sphinx-rtd-theme sphinx-tabs breathe exhale sphinxcontrib-spelling
pip3 install sphinx sphinx-rtd-theme sphinx-tabs
# build doc (only)
mkdir build
......
###############################################################################
# Copyright (c) 2021 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
#
# 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
###############################################################################
import os
import shutil
from textwrap import dedent
from sphinx.directives.other import TocTree
class ARGS:
"""Default argument values"""
API_DOC_BUILD_DEACTIVATED = "off"
DEFAULT_API_DOC_BUILD = API_DOC_BUILD_DEACTIVATED
DEFAULT_API_DOC_PATH = "api"
DEFAULT_API_DOC_TITLE = "Source Code Documentation"
def api_doc_build_activated(config):
"""True if api_doc_build is NOT set to deactivated"""
return config.api_doc_build.lower() != ARGS.API_DOC_BUILD_DEACTIVATED
def purge_api_doc_path(app, config):
"""Purges the rst files from the build folder"""
api_doc_path = os.path.join(app.srcdir, config.api_doc_path)
if os.path.exists(api_doc_path):
shutil.rmtree(api_doc_path, ignore_errors=True)
def on_config_inited(app, config):
"""
Sphinx Event Hook:
Activates and configures breath and exhale if api_doc_build is active
"""
if api_doc_build_activated(config):
app.setup_extension('breathe')
app.setup_extension('exhale')
config.exhale_args = {
# These arguments are required
"containmentFolder": f"./{config.api_doc_path}",
"rootFileName": "index.rst",
"rootFileTitle": f"{config.api_doc_title}",
"doxygenStripFromPath": "../../../sim",
# Suggested optional arguments
"createTreeView": True,
# TIP: if using the sphinx-bootstrap-theme, you need
# "treeViewIsBootstrap": True,
"exhaleExecutesDoxygen": True,
"exhaleDoxygenStdin": dedent('''
INPUT = ../../../sim/src
WARN_IF_UNDOCUMENTED = NO
WARN_AS_ERROR = NO
PREDEFINED += DOXYGEN_SHOULD_SKIP_THIS
GENERATE_HTML = NO
RECURSIVE = YES
FULL_PATH_NAMES = YES
QUIET = YES
FILE_PATTERNS = *.cpp *.h
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
SKIP_FUNCTION_MACROS = NO
EXPAND_ONLY_PREDEF = NO
''')}
config.breathe_projects = {"openpass": "doxyoutput/xml"}
config.breathe_default_project = "openpass"
config.cpp_id_attributes = ['Q_DECL_IMPORT']
else:
purge_api_doc_path(app, config)
class ApiDoc(TocTree):
"""
Customized TocTree Directive `.. toctree-api::`
Enhances the regular toctree by a conditional :api-doc: entry.
If api_doc_build is active :api-doc: will be replaced by the
entry point to the api documentation such as api/index.rst
Use config values `api_doc_path` and `api_doc_title` to adjust
subdirectory and title shown in the toc, respectively.
Example:
.. toctree-api::
:caption: Developer Information
:glob:
developer_information/*
:api-doc:
"""
API_DOC_DIRECTIVE = "toctree-api"
API_DOC_TOKEN = ':api-doc:'
@property
def api_doc_active(self):
return api_doc_build_activated(self.state.document.settings.env.config)
@property
def api_doc_entry_point(self):
config = self.state.document.settings.env.config
return f'/{config.api_doc_path}/index.rst'
def _parse_conditional_api_doc(self):
"""
Scans for the API_DOC_TOKEN and transforms it if active
Returns a new list of toc entries (= self.content)
"""
toc_entries = list()
for toc_entry in self.content:
if toc_entry.strip() == self.API_DOC_TOKEN:
if self.api_doc_active:
toc_entries.append(self.api_doc_entry_point)
else:
toc_entries.append(toc_entry)
return toc_entries
def run(self):
self.content = self._parse_conditional_api_doc()
return super().run()
def setup(app):
app.connect('config-inited', on_config_inited)
app.add_directive(ApiDoc.API_DOC_DIRECTIVE, ApiDoc)
app.add_config_value(name='api_doc_build',
default=ARGS.DEFAULT_API_DOC_BUILD, rebuild='env')
app.add_config_value(name='api_doc_path',
default=ARGS.DEFAULT_API_DOC_PATH, rebuild='env')
app.add_config_value(name='api_doc_title',
default=ARGS.DEFAULT_API_DOC_TITLE, rebuild='env')
return {'version': '0.1'}
......@@ -24,15 +24,15 @@ Unspecified arguments will be defaulted (*default values in []*).
The simulation supports the following arguments:
* *--logLevel* [0] :
* *-\-logLevel* [0] :
Logging level between 0 (minimum) and 5 (maximum - debug core)
* *--logFile* [opSimulation.log]* :
* *-\-logFile* [opSimulation.log]* :
Name of the log file
* *--lib* [modules] :
* *-\-lib* [modules] :
Path of the libraries (relative or absolute)
* *--configs* [configs] :
* *-\-configs* [configs] :
Path for writing outputs (relative or absolute)
* *--results* [results] :
* *-\-results* [results] :
Path for writing outputs (relative or absolute)
.. _simulation_scheduler:
......
......@@ -158,12 +158,12 @@ In the currently implementation, these points must be located - otherwise the ag
.. _world_trafficsigns:
Traffic Signs and Road Markings
-------------------------------
Traffic Signs, Road Markings and TrafficLights
----------------------------------------------
The world currently supports a variety of traffic signs and road markings.
Both are defined in OpenDRIVE as "RoadSignal".
At the moment it can only interpret traffic signs according to the German regulations and US regulations.
The world currently supports a variety of traffic signs, road markings and traffic lights.
All of these are defined in OpenDRIVE as "RoadSignal".
At the moment it can only interpret traffic signs and road markings according to the German regulations and US regulations and traffic lights according the the OpenDRIVE appendix.
Traffic signs can contain optional supplementary traffic signs. Supplementary signs are dependent on a main traffic sign and contain additional information.
For Germany the types are based on the StVO (see: https://www.bast.de/BASt_2017/DE/Verkehrstechnik/Fachthemen/v1-verkehrszeichen/vz-download.html).
......@@ -251,6 +251,24 @@ The following traffic signs are supported for the United States:
DoNotEnter R5-1
============================================= ========= ========================================================
The following traffic lights are supported:
.. table::
:class: tight-table
============================================= =============== ======= ===============
TrafficLight OpenDRIVE Type Subtype Value and Units
============================================= =============== ======= ===============
Standard traffic light (red, yellow, green) 1.000.001 - -
Left arrows 1.000.011 10 -
Right arrows 1.000.011 20 -
Upwards arrows 1.000.011 30 -
Left und upwards arrows 1.000.011 40 -
Right und upwards arrows 1.000.011 50 -
============================================= =============== ======= ===============
These traffic lights are controlled by OpenScenario.
.. _world_lanemarkings:
Lane Markings
......
..
************************************************************
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
************************************************************
.. toctree::
:caption: Developer Doc
api/index.rst
......@@ -11,27 +11,18 @@
# Configuration file for the Sphinx documentation builder. See also:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
import os
import os
import sys
import datetime
import sphinx_rtd_theme
from textwrap import dedent
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.append(os.path.abspath("_ext"))
# -- Project information -----------------------------------------------------
project = 'openPASS'
copyright = f'{datetime.datetime.now().year} OpenPASS Working Group'
author = 'in-tech GmbH'
generate_api_doc = '-DWITH_API_DOC=ON' in sys.argv
if generate_api_doc:
sys.argv.remove('-DWITH_API_DOC=ON')
# -- Version is generated via cmake
version_file = 'version.txt'
if os.path.exists(version_file):
......@@ -49,6 +40,7 @@ extensions.append("sphinx_rtd_theme")
extensions.append('sphinx.ext.todo')
extensions.append('sphinx_tabs.tabs')
extensions.append('sphinx.ext.imgmath')
extensions.append('api_doc')
templates_path = ['_templates']
......@@ -62,52 +54,6 @@ pdf_fit_mode = "shrink" # literal blocks wider than frame
pdf_language = "en_US"
pdf_page_template = 'cutePage'
# -- Options developer documentation --------------------------------------
if generate_api_doc:
extensions.append('breathe')
extensions.append('exhale')
breathe_projects = {"openpass":"doxyoutput/xml"}
breathe_default_project = "openpass"
cpp_id_attributes = ['Q_DECL_IMPORT']
# -- Setup the exhale extension ----------------------------------------------
exhale_args = {
# These arguments are required
"containmentFolder": "./api",
"rootFileName": "index.rst",
"rootFileTitle": "Source Code Documentation",
"doxygenStripFromPath": "@OP_REL_SIM@",
# Suggested optional arguments
"createTreeView": True,
# TIP: if using the sphinx-bootstrap-theme, you need
# "treeViewIsBootstrap": True,
"exhaleExecutesDoxygen": True,
"exhaleDoxygenStdin": dedent('''
INPUT = @OP_REL_SIM@/src
WARN_AS_ERROR = NO
PREDEFINED += DOXYGEN_SHOULD_SKIP_THIS
GENERATE_HTML = NO
RECURSIVE = YES
FULL_PATH_NAMES = YES
QUIET = YES
FILE_PATTERNS = *.cpp *.h
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
SKIP_FUNCTION_MACROS = NO
EXPAND_ONLY_PREDEF = NO
''')
}
# make TOC available
with open('api.rst.template', 'r') as api_toc_template:
with open('api.rst', 'w') as api_toc:
api_toc.write(api_toc_template.read())
else:
# wipe TOC for developer doc by creating an empty file
open('api.rst', 'w').close()
# -- Options for HTML output -------------------------------------------------
html_static_path = ['_static']
......@@ -117,6 +63,9 @@ html_short_title = 'OpenPASS|Doc'
html_favicon = '_static/openPASS.ico'
html_logo = '_static/openPASS.png'
# -- Options for API DOC -----------------------------------------------------
api_doc_title = "Source Code Documentation"
# -- Define global replacements ----------------------------------------------
# See https://documentation.help/Sphinx/config.html
rst_epilog = """
......
......@@ -107,7 +107,7 @@ Build Kit
**Add and select MSYS2/MinGW64 Build Kit:**
1. Execute ``Ctrk+Shift+P``: ``CMake: Edit User-Local CMake Kits``
1. Execute ``Ctrl+Shift+P``: ``CMake: Edit User-Local CMake Kits``
2. Insert/Update:
......@@ -118,20 +118,20 @@ Build Kit
:download:`Download <_static/vscode/config/win/cmake-tools-kits.json>`
3. ``Ctrk+Shift+P``: ``CMake: Select a Kit`` = ``MinGW64``
3. ``Ctrl+Shift+P``: ``CMake: Select a Kit`` = ``MinGW64``
.. tab:: Linux
**Select System Build Kit:**
``Ctrk+Shift+P``: ``CMake: Select a Kit`` = ``GCC 10.2.0``
``Ctrl+Shift+P``: ``CMake: Select a Kit`` = ``GCC 10.2.0``
See also :ref:`prerequisites`.
User Settings
+++++++++++++
1. Execute ``Ctrk+Shift+P``: ``Preferences Open Workspace Settings (JSON)``
1. Execute ``Ctrl+Shift+P``: ``Preferences Open Workspace Settings (JSON)``
2. Insert/Update:
......@@ -159,7 +159,7 @@ User Settings
C++ and IntelliSense
++++++++++++++++++++
1. Execute ``Ctrk+Shift+P``: ``C/C++: Edit Configurations (JSON)``
1. Execute ``Ctrl+Shift+P``: ``C/C++: Edit Configurations (JSON)``
2. .. literalinclude:: _static/vscode/config/c_cpp_properties.json
:caption: c_cpp_properties.json
......@@ -171,7 +171,7 @@ C++ and IntelliSense
Configure the Build
+++++++++++++++++++
Execute ``Ctrk+Shift+P``: ``CMake: Configure``
Execute ``Ctrl+Shift+P``: ``CMake: Configure``
CMake should now be able to configure the project.
......@@ -182,7 +182,7 @@ Read :ref:`cmake` or :ref:`prerequisites` for more information.
Some changes such as changing the build type (Debug/Release) will cause CMake to updates the configuration automatically.
Other changes won't trigger an update, such as changing the paths to libraries (`CMAKE_PREFIX_PATH`), the cmake cache needs to be cleared before reconfiguration:
``Ctrk+Shift+P`` > ``CMake: Delete Cache and Reconfigure``
``Ctrl+Shift+P`` > ``CMake: Delete Cache and Reconfigure``
Debug Targets
+++++++++++++
......
......@@ -36,7 +36,7 @@ Based on these the simulation core calculates different simulation runs and comp
:maxdepth: 1
user_guide/*
.. toctree::
:caption: Advanced topics
:glob:
......@@ -44,15 +44,13 @@ Based on these the simulation core calculates different simulation runs and comp
advanced_topics/*
..
.. include:: api.rst
.. toctree::
.. toctree-api::
:caption: Developer Information
:glob:
:maxdepth: 1
developer_information/*
:api-doc:
.. toctree::
:caption: Other Information
......
......@@ -166,8 +166,7 @@ The first set of dependencies we need to install in order to successfully compil
apt install gcc
apt install g++
apt install graphviz
apt install libprotobuf-dev
apt install protobuf-compiler # when building osi
apt install libqt5xmlpatterns5-dev
apt install qt5-default
apt install zlib1g-dev
......@@ -241,15 +240,24 @@ The following directory tree shows the folder structure, which will be created b
├── FMILibrary
│ ├── include
│ └── lib
└── osi
├── osi
│ ├── include
│ └── lib
├── protobuf
│ ├── bin
│ ├── include
│ └── lib
└── protobuf-shared
├── bin
├── include
└── lib
└── lib
In the folder structure above:
- ``C:\OpenPASS\thirdParty`` refers to a temporary directory used to built the prerequisites from source, **not** the ``simopenpass`` repository
- ``FMILibrary`` is the install directory of the ``Functional Mock-up Interface (FMI)`` when build from source
- ``osi`` is the install directory of the ``Open Simulation Interface (OSI)`` when build from source.
- ``FMILibrary`` is the install directory of the :term:`Functional Mock-up Interface (FMI) <FMI>` when build from source
- ``osi`` is the install directory of the :term:`Open Simulation Interface (OSI) <OSI>` when build from source.
- ``protobuf`` and ``protobuf-shared`` are the install directories of ``Google Protocol Buffers`` for shared and static builds, respectively.
.. tab:: Linux
......@@ -259,18 +267,36 @@ The following directory tree shows the folder structure, which will be created b
├── FMILibrary
│ ├── include
│ └── lib
└── osi
├── osi
│ ├── include
│ └── lib
├── protobuf
│ ├── bin
│ ├── include
│ └── lib
└── protobuf-shared
├── bin
├── include
└── lib
└── lib
In the folder structure above:
- ``~/OpenPASS/thirdParty`` refers to a temporary directory used to built the prerequisites from source, **not** the ``simopenpass`` repository
- ``FMILibrary`` is the install directory of the ``Functional Mock-up Interface (FMI)`` when build from source
- ``osi`` is the install directory of the ``Open Simulation Interface (OSI)`` when build from source.
- ``FMILibrary`` is the install directory of the :term:`Functional Mock-up Interface (FMI) <FMI>` when build from source
- ``osi`` is the install directory of the :term:`Open Simulation Interface (OSI) <OSI>` when build from source.
- ``protobuf`` and ``protobuf-shared`` are the install directories of ``Google Protocol Buffers`` for shared and static builds, respectively.
On the basis of this structure, we will explain further steps.
Build and Install Protobuf
~~~~~~~~~~~~~~~~~~~~~~~~~~
Google Protocol Buffers provide the foundation of :term:`OSI` (see also :ref:`building_osi`).
Due to the usage of OSI different situations (|Op| executables, libraries, tests, :term:`FMUs <FMU>`, etc.) static and shared libraries of protobuf have to be provided.
Please refer to :ref:`building_protobuf` for detailed instructions.
.. _building_osi:
Build and Install OSI
......@@ -500,7 +526,7 @@ Build and Install FMIL
.. code-block::
dos2unix src/Import/src/FMI1/fmi1_import_capi.c src/Import/src/FMI2/fmi2_import_capi.c src/Util/include/JM/jm_portability.h
patch -l -p1 "<path/to>/fmi-library-2.0.3-fixes.patch"
patch -l -p1 < "<path/to>/fmi-library-2.0.3-fixes.patch"
#. Enter build directory
......
......@@ -108,6 +108,8 @@ The above directory structure will be created by following the instructions of t
.. code-block::
cp -r osi /C/simopenpass/deps/thirdParty
cp -r protobuf /C/simopenpass/deps/thirdParty
cp -r protobuf-shared /C/simopenpass/deps/thirdParty
cp -r FMILibrary /C/simopenpass/deps/thirdParty
.. tab:: Linux
......@@ -115,6 +117,8 @@ The above directory structure will be created by following the instructions of t
.. code-block::
cp -r osi ~/simopenpass/deps/thirdParty
cp -r protobuf ~/simopenpass/deps/thirdParty
cp -r protobuf-shared ~/simopenpass/deps/thirdParty
cp -r FMILibrary ~/simopenpass/deps/thirdParty
.. _ref_prerequisites:
......@@ -165,7 +169,7 @@ The above directory structure will be created by following the instructions of t
.. code-block::
cmake -G "MSYS Makefiles" \
-D CMAKE_PREFIX_PATH="C:/msys64/mingw64/bin;C:/simopenpass/deps/thirdParty/FMILibrary;C:/simopenpass/deps/thirdParty/osi" \
-D CMAKE_PREFIX_PATH="C:/msys64/mingw64/bin;C:/simopenpass/deps/thirdParty/FMILibrary;C:/simopenpass/deps/thirdParty/osi;C:/simopenpass/deps/thirdParty/protobuf;C:/simopenpass/deps/thirdParty/protobuf-shared" \
-D CMAKE_INSTALL_PREFIX=C:/OpenPASS/bin/core \
-D CMAKE_BUILD_TYPE=Release \
-D USE_CCACHE=ON \
......@@ -192,7 +196,7 @@ The above directory structure will be created by following the instructions of t
.. code-block::
cmake -D CMAKE_PREFIX_PATH="$HOME/simopenpass/deps/thirdParty/FMILibrary;$HOME/simopenpass/deps/thirdParty/osi" \
cmake -D CMAKE_PREFIX_PATH="$HOME/simopenpass/deps/thirdParty/FMILibrary;$HOME/simopenpass/deps/thirdParty/osi;$HOME/simopenpass/deps/thirdParty/protobuf;$HOME/simopenpass/deps/thirdParty/protobuf-shared" \