1.3.3. How to write Docs¶

As always it is recommended to write Docs inside the docker container since there everything necessary is already installed. Assumed that you followed the instructions on Visual Studio Code as standardized IDE.

1.3.3.1. How to add a new ros package to the docs?¶

1.3.3.1.1. Python Packages¶

Create a new folder mkdir docs/source/modules/<module_name>
Add the scripts directory of the new module to new docs conf file docs/conf.py by adding the line:
```
sys.path.insert(0, os.path.abspath('../src/<module_name>/scripts'))
```
Create a new file under docs/source/modules/<module_name>/ros_package.rst, paste and adapt the following content:
```
<Module Title> ROS Package
==========================

.. ros:autopackage:: <module_name>
```

Add the following line to docs/generate_docs.sh

sphinx-apidoc -f -M -o source/modules/<module_name>/ ../src/<module_name>/scripts/ -H "<Module Title>" -t template_dir/ -d 2

1.3.3.1.2. C++ Packages¶

Create a new folder mkdir docs/source/modules/<module_name>

Example:
```
mkdir docs/source/modules/path_planning
```

Create a new file under docs/source/modules/<module_name>/ros_package.rst, paste and adapt the following content:

<Module Title> ROS Package
==========================

.. ros:autopackage:: <module_name>

Example:

mkdir docs/source/modules/path_planning/ros_package.rst

Path Planning ROS Package
=========================

.. ros:autopackage:: path_planning

Create a new file under docs/source/modules/<module_name>/<file_name(w/o extension)>.rst, for each file you want documentation generated for and adapt the following content:

Hint

Best practice is to write Doxygen documentation in your .hpp header files, as these define your public interface. Link to the .hpp files here unless you specifically need to document implementation details from .cpp files.
```
<File Title>
============

.. doxygenfile:: <file_name>
   :project: AS ROS
```
Example:
```
mkdir docs/source/modules/path_planning/path_planning_lib.rst
```
```
Path Planning Library
=====================

.. doxygenfile:: path_planning_lib.hpp
   :project: AS ROS
```

Create a new file under docs/source/modules/<module_name>/modules.rst, paste and adapt the following content, adding all files you want documentation generated for:

<Module Title>
==============

.. toctree::
   :maxdepth: 2

   ros_package
   <file_name(w/o extension)>

Example:

mkdir docs/source/modules/path_planning/modules.rst

Path Planning
=============

.. toctree::
   :maxdepth: 2

   ros_package
   path_planning_lib

Add the following line to docs/generate_docs.sh

sphinx-apidoc -f -M -o -T source/modules/<module_name>/ -H "<Module Title>" -t template_dir/ -d 2

Example:

sphinx-apidoc -f -M -o -T source/modules/path_planning/ -H "<Path Planning>" -t template_dir/ -d 2

1.3.3.1.3. Add and generate the Docs¶

Change directory into docs
Add the tree of content file of the newly added module (modules.rst) to the root tree of the content file (docs/source/modules/index.rst) of the modules documentation
```
``<module_name>/modules``
```
Be sure that you build and sourced the catkin workspace (Build and source the catkin workspace)
Execute inside the docs directory:
```
./generate_docs.sh
```

1.3.3.2. How to write Docs generelly (e.g. this page)?¶

Open your local container in VSCode (Connect to an AS ROS container with VSCode)
Find the file or create the file you want to edit under docs/source/
1. if you created a new file, you need to add it to some toctree, so that a link to file is created
Open the Preview for the file you are currently editing: Press Strg + P and choose ReStructedText: Open Preview to the side entry
Start editing

1.3.3.3. How to add a custom page to a automatically documented python package¶

If you want to add a custom page to a automatically documented python package, e.g. add instructions how to setup the control module.

Since executing ./generate_docs will override the content of the respective modules.rst file, you cannot just add your new .rst to the modules.rst to add it to the table of content.

Instead you can insert an _ before the .rst file ending, e.g. setup_.rst. The modules.rst file will automatically recognize the new file then and will include it when you execute make html or ./generate.sh the next time.

1.3.3.4. How to update the Docs?¶

The commands should be executed within the container.

If you added a new TableOfContent (TOC) Entry, you should first clean the whole build directory, so that the TOC is updated on every page:
```
make clean
```
Always produce new documentations:
```
make html
```