.. _write-docs:

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 :ref:`vscode`.

How to add a new ros package to the docs?
-----------------------------------------

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:

   .. code-block:: python

      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:

   .. code-block:: rst

      <Module Title> ROS Package
      ==========================
      
      .. ros:autopackage:: <module_name>

#. Add the following line to ``docs/generate_docs.sh``

   .. code-block:: bash

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


C++ Packages
^^^^^^^^^^^^

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

   Example:

   .. code-block:: bash

      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:

   .. code-block:: rst

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

      .. ros:autopackage:: <module_name>

   Example:

   .. code-block:: bash

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

   .. code-block:: 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.

   .. code-block:: rst

      <File Title>
      ============

      .. doxygenfile:: <file_name>
         :project: AS ROS

   Example:

   .. code-block:: bash

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

   .. code-block:: 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:

   .. code-block:: rst

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

      .. toctree::
         :maxdepth: 2

         ros_package
         <file_name(w/o extension)>
   
   Example:

   .. code-block:: bash

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

   .. code-block:: rst

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

      .. toctree::
         :maxdepth: 2

         ros_package
         path_planning_lib

#. Add the following line to ``docs/generate_docs.sh``

   .. code-block:: bash

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

   Example:
   
   .. code-block:: bash

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


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

   .. code-block::

      ``<module_name>/modules``

#. Be sure that you build and sourced the catkin workspace (:ref:`build_and_source_catkin`)

#. Execute inside the ``docs`` directory:

   .. code-block::

      ./generate_docs.sh
   


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

#. Open your local container in VSCode  (:ref:`vscode-as-ros-container`)

#. Find the file or create the file you want to edit under ``docs/source/``

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

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.

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:

   .. code-block:: bash

      make clean

#. Always produce new documentations:

   .. code-block:: bash

      make html