Developer documentation workflow¶

What you need to know¶

For developer documentation, we use Doxygen comments extensively throughout NEST.

After installing NEST, you can extract comments from the source code with make docs. A doxygen folder with HTML files will be generated in the doc folder in your source directory.

Note

This workflow shows you how to create developer documentation for NEST. For the user documentation, please refer to our User documentation workflow.

Instructions¶

Install Doxygen and graphviz.

If you are a Linux user, type:
```
sudo apt install doxygen graphviz
```
For macOS, please use Homebrew:
```
brew install doxygen graphviz
```
Navigate to, or create a build directory. See Install NEST.
Add the -Dwith-devdoc=ON flag to your regular CMake command:
```
cmake -Dwith-devdoc=ON
```

Generate HTML:
```
make docs
```
Preview documentation:
```
cd doc/doxygen/html
browser index.html
```

build workflow¶

local build

if make docs is run

doxygen runs and outputs xml
python script (ext?) is triggered and outputs json task: get class names of nest module from xml
app(conf.py) connects json to jinja template in rst file
breathe extension reads the rst file and extracts desired info from xml and outputs html

xml snippet:
------------

<compoundname>nest::ArchivingNode</compoundname>

json:
-----

["nest::ArchivingNode", "nest::Connection", . . .]

rst file with jinja template:
-----------------------------

{% for item in json_list %}
.. doxgygenclass:: {{ item }}
{% endfor %}

rendered rst file
-----------------

.. doxygenclass:: nest::ArchivingNode

Requirementts for our C++ files

doxgyen comments (format, when, what)

special groups? or keywords?

possible rst markup

Doxyfile

configuration for doxyen
output xml
include svg, dot graphs