User-level documentation workflow

What you need to know

We use Sphinx to generate documentation and Read the Docs to publish it. Sphinx uses reStructuredText. 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 directory within the NEST source code repository on GitHub.

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

This workflow aims for the concept of user-correctable documentation.

Alternative text

Note

This workflow shows you how to create user-level documentation for NEST. For developer documentation, please refer to our Developer documentation workflow.

Changing the documentation

If you notice any errors or weaknesses in the documentation, please submit an Issue in our GitHub repository.

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

Setting up your environment

Our conda environment will enable you to generate documentation for NEST.

If you are using Linux and want to install a full development environment:

  1. Install conda (we recommend miniconda).

  2. Switch to the doc folder in the source directory:

cd </path/to/nest_source>/doc

  1. Create and activate the environment:

conda update -n base -c defaults conda
conda env create --file nest_doc_conda_env.yml
conda activate nest-doc

  1. If you want to deactivate or delete the build environment:

conda deactivate
conda remove --name nest-doc --all

Generating documentation with Sphinx

Now that you activated your environment, you can generate HTML files using Sphinx.

Rendering HTML

Using Sphinx, you can build documentation locally and preview it offline:

  1. Go to the doc folder in the source directory:

cd </path/to/nest_source>/doc

  1. Generate HTML files:

make html

  1. Preview files. They are then located in ./_build/html:

cd ./_build/html
browser filename.html

Editing and creating pages

To edit existing reStructuredText files or to create new ones, follow the steps below:

  1. You can edit and/or add .rst files in the doc directory using your editor of choice.

  2. If you create a new page, open contents.rst in the doc directory and add the file name under .. toctree::. This will ensure it appears on the NEST simulator documentation’s table of contents.

  3. If you rename or move a file, please make sure you update all the corresponding cross-references.

  4. Save your changes.

  5. Re-render documentation as described above.

Previewing on Read the Docs (optional)

Proceed as follows to preview your version of the documentation on Read the Docs.

  1. Check that unwanted directories are listed in .gitignore:

_build
_static
_templates

  1. Add, commit and push your changes to GitHub.

  2. Go to Read the Docs. Sign up for an account if you don’t have one.

  3. Import the project.

  4. Enter the details of your project in the repo field and hit Create.

  5. Build your documentation.

This allows you to preview your work on your Read the Docs account. In order to see the changes on the official NEST simulator documentation, please submit a pull request.

Creating pull request

Once your documentation work is finished, you can create a pull request to the master branch of the NEST Source Code Repository. Your pull request will be reviewed by the NEST Documentation Team!