User-level documentation workflow¶

Overview of workflow¶

We use Sphinx to generate documentation and Read the Docs to publish it. Sphinx uses reStructuredText as the base format for the documentation. To learn more about the syntax, check out this quick reference.

The NEST Simulator documentation lives alongside its code. It is contained in the doc/htmldoc directory within the NEST source code repository on GitHub.

We work with GitHub as a web-based hosting service for Git. Git allows us to keep our versions under control, with each release of NEST having its own documentation.

flowchart TB sphinx:::TextPosition classDef TextPosition padding-right:25em; classDef orangeFill color:#fff, stroke:#f63, stroke-width:2px, fill:#f63; classDef blueFill color:#fff, stroke:#072f42, stroke-width:2px, fill:#072f42; classDef brownFill color:#fff, stroke:#652200, stroke-width:2px, fill:#652200; subgraph sphinx[SPHINX] read(Read source files):::blueFill-->ext read-->custom subgraph Parse_rst ["Parse rst"] ext(sphinx_extensions):::blueFill custom(custom_extensions):::blueFill end Parse_rst-->build build(Build output formats):::blueFill end subgraph EDIT SOURCE FILES source(repo: nest/nest-simulator):::orangeFill-- sphinx-build-->read end subgraph OUTPUT["REVIEW OUTPUT"] direction TB build--local filesystem-->local(_build directory):::brownFill build--hosting platform-->rtd(Read the Docs):::brownFill local-->HTML(HTML):::brownFill rtd-->HTML end

Figure 45 Overview of documentation build. Drag and zoom to explore.¶

Contribute to the documentation¶

You can make changes directly to your forked copy of the NEST source code repository and create a pull request. Just follow the workflow below!

If you have not done so alrealdy first

Fork the nest-simulator repository (see here for details on first time setup)
Clone the nest-simulator:

git clone git@github.com:<my-username>/nest-simulator

Create a branch to a make your changes

git checkout -b <my-new-feature>

Set up your environment¶

Using the Conda package (includes everything to build NEST, including documentation)¶

For details on Conda, see Tips for installing NEST with conda

cd <nest_source_dir>/
conda env create -p conda/
conda activate conda/

If you later on want to deactivate or delete the build environment:

conda deactivate
rm -rf conda/

Using pip (includes packages for documentation only)¶

If you want to install only a minimal set of packages for building the documentation and avoid using Conda, you can use pip:

pip3 install -r <nest_source_dir>/doc/requirements.txt

If you use pip, install pandoc from your platform’s package manager (e.g. apt):

sudo apt-get install pandoc

Building plantuml diagrams locally

The plantuml diagrams require additional requirements to make them work in a local build.

You will need to

check if you have Java installed. The minimum version needed is Java 8. (e.g., to install the latest available version on Ubuntu: apt install jre-default)
Download the plantuml jar file (Minimum version is 1-2023-10)
Move the jar file to /tmp/plantuml.jar
To see if plantuml diagrams render correctly after building the documentation you can take a look at our Test uml page.

Edit and create pages¶

You can now edit or add new files with your editor of choice. Most documentation files are written in reStructuredText and are found in the doc/htmldoc directory. There are some exceptions, detailed below. If you’re unfamiliar with reStructuredText, you can find some helpful hints here.

Please see our documentation style guide for information on how to write good documentation in NEST.

Where to find documentation in the repository¶

Most documentation is located in doc/htmldoc with some exceptions.

If you want to edit Model docs, PyNEST API files, or PyNEST examples, you will need to edit the source files:

Type of documentation	Source location
Model docs	`nest-simulator/models/*.h` in the section BeginUserDocs
PyNEST API	`nest-simulator/pynest/nest/*/.py`
PyNEST examples	`nest-simulator/pynest/examples/*/.py`

Note

Also consider that any new pages you create need to be referenced in the relevant table of contents.

Review changes you made¶

To check that the changes you made are correct in the HTML output, you will need to build the documentation locally with Sphinx.

Navigate to the doc/htmldoc folder:

cd nest-simulator/doc/htmldoc

Build the docs:

sphinx-build . ../_build/html -b html

Preview files. They are located in doc/_build/html

<browser> ../_build/html/index.html

Tip

You can also build the user documentation in the build directory with CMake:

cmake -Dwith-userdoc=ON </path/to/NEST/src>
make docs

Create a pull request¶

Once you’re happy with the changes, you can submit a pull request on Github from your fork. Github has a nice help page that outlines the process for submitting pull requests.

Reviewers will be assigned and go through your changes.

If you are a first time contributor, we ask that you fill out the NEST Contributor Agreement form to transfer your copyright to the NEST initiative and send it to info [at] nest-initiative.org.

Tip

If you notice any errors or weaknesses in the documentation, you can also submit an Issue on GitHub.

Read the Docs¶

NEST documentation is hosted on Read the Docs. If you would like to view the documentation on Read the Docs, you can set up your own account and link it with your Github account.

See this guide for more information.