.. _code_documenting:
==================================
Documenting your developments
==================================
.. contents::
Where should you document your developments? Well, at several places,
indeed, depending on the documentation we are talking about:
Code documentation
------------------
This is quite easy indeed. It's excellent practice to add
`docstring `_ to your
python code. The good part of it is that tools like pyDev can automatically
read it. Also your python shell can (try ``help()``), and so does iPython
(just use ``?`` for example). Python stores every docstring in
the special attribute ``__doc__``.
Pylint will, by default, complain for every method/class/function left without
a docstring.
Release documentation
---------------------
Releases documentation can be found in 2 places: release notes, and github wiki:
* release notes are automatically created from the first comment in the pull
requests, please describe the changes between BEGRINRELEASENOTES and
ENDRELEASENOTES as presented by the template provided
* The github wiki can contain a section, for each DIRACGrid repository,
highlighting update operations, for example the DIRAC releases notes are
linked from the `DIRAC wiki main page `_.
Full development documentation
------------------------------
As said at the beginning of this guide, this documentation is in git at
`DIRAC/docs `_.
It is very easy to contribute to it, and you are welcome to do that. You don't
even have to clone the repository: github lets you edit it online.
This documentation is written in ``RST`` and it is compiled using
`sphinx `_.
Some parts of the documentation can use UML diagrams. They are generated from .uml files
with `plantuml `_. Sphinx support plantuml but ReadTheDocs
didn't, so you have to convert .uml in .png with ``java -jar plantuml.jar file.uml``.
.. _codedocumenting_parameters:
Component Options documentation
-------------------------------
The agent, service and executor options are documented in their respective
module docstring via literal include of their options in the
ConfigTemplate.cfg::
.. literalinclude:: ../ConfigTemplate.cfg
:start-after: ##BEGIN MyComponent
:end-before: ##END
:dedent: 2
:caption: MyComponent options
Around the section in the *ConfigTemplate.cfg* configuring the component the
*##BEGIN MyComponent* and *##END* tags need set so that the include is
restricted to the section belonging to the component. The options *:dedent:* and
*:caption:* are optional, but create a nicer output.
.. _building_documentation:
Building the Documentation
--------------------------
The DIRAC documentation is created using ``sphinx`` and makes use of the
``diracdoctools`` to create the code documentation, command references, and
concatenate the ``ConfigTemplates`` into one file. The ``diracdoctools`` are
located in the ``DIRAC/docs`` folder, but they can be ``pip installed`` for use
outside of DIRAC.
For local development the easiest way to build the docs is by running these
commands from a standard Python 3 DIRAC development environment (see
:ref:`create-dev-env-conda`.)
.. code-block:: bash
pip install docs/
cd docs
make htmlall
python -m http.server -d build/html/
You can now browse the docs locally by going to the URL shown in your terminal.
In the sphinx configuration file (``source/conf.py``), the functionality can
then be called to create code reference, command reference and concatenated CFG
files.
.. literalinclude:: ../../conf.py
:start-after: # AUTO SETUP START
:end-before: # AUTO SETUP END
:caption: docs/source/conf.py
The configuration for ``diracdoctools`` is done via a configuration file
located in the docs folder. Just copy the file ``DIRAC/docs/docs.conf`` and
adapt it to your needs. Note that some options are mandatory, this is indicated in the comments to them.
.. literalinclude:: ../../../docs.conf
:caption: docs/docs.conf
For local testing of the documentation, the scripts can also be called
directly, like this example from the ``Makefile`` shows.
.. literalinclude:: ../../../Makefile
:caption: docs/Makefile
:start-after: # AUTO MAKE START
:end-before: # AUTO MAKE END
Code Reference
``````````````
The code reference is either created by calling ``run`` from
``diracdoctools.cmd.codeReference`` or by invoking the script
``dirac-docs-build-code.py``. This creates an ``rst`` file for each python
file, using ``autodoc`` to document all classes inside those modules. The
actual documentation is build when sphinx is invoked, which must be able to
import the modules and all their dependencies
Command Reference
`````````````````
The command references can be created by calling ``run`` from
``diracdoctools.cmd.commandReference``, or by calling the
``dirac-docs-build-command.py`` script. ``[commands.section]`` will result in a
list of commands with links to their documentation, which is based on the output
of their ``--help``. By adding subsections like a ``[commands.section.g1]`` you can additionally group commands.
The resulting ``index.rst`` has to be included explicitly in the documentation.
.. note:: starting with 8.0, to add a link to the command description use command name in a reference, e.g.: `dirac-admin-sysadmin-cli`.
.. warning:: Starting with 8.0, the option ``indexFile`` is no longer available. If you created an RST file and
decided to add commands yourself, you simply do not need to describe it in the `docs.conf`.
.. note ::
The parsing of the ``--help`` output is extremely limited and naive. You must not end a line with a
colon ``:`` unless you intend to create a verbatim block after it.
CFG File
````````
If you developed your own systems, you can concatenate all the settings defined
in ``ConfigTemplate.cfg`` files into one large file. You need a base
``dirac.cfg`` file and a location where to put the final result