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 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/userdoc
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.
This workflow aims for the concept of user-correctable documentation.
Note
This workflow shows you how to create user-level documentation for NEST. For the 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¶
We recommend that you set up a full NEST developer environment using Conda (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/
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
Generating documentation with Sphinx¶
Now that you activated your environment, you can generate HTML files using Sphinx.
Rendering HTML¶
You can build and preview the documentation locally by running the following commands.
1. Go to the build directory of NEST (i.e., the
directory where you ran cmake
)
cd nest-simulator-x.y.z-build
Generate HTML files
make html
Preview files. They are located in
doc/userdoc/html
browser doc/userdoc/html/index.html
To install the documentation under <nest_install_dir>
along with
the rest of NEST, the make html
command can be followed by
make install
If you want to view the files after installation, you can run
browser <nest_install_dir>/share/doc/nest/html/index.html
Editing and creating pages¶
To edit existing reStructuredText files or to create new ones, follow the steps below:
You can edit and/or add
.rst
files in thedoc/userdoc
directory using your editor of choice.If you create a new page, open
contents.rst
in thedoc/userdoc
directory and add the file name under.. toctree::
. This will ensure it appears on the NEST simulator documentation’s table of contents.If you rename or move a file, please make sure you update all the corresponding cross-references.
Save your changes.
Re-render documentation as described above.
You can find our full documentation style guide here.
Previewing on Read the Docs (optional)¶
Proceed as follows to preview your version of the documentation on Read the Docs.
Check that unwanted directories are listed in
.gitignore
:
_build
_static
_templates
Add, commit and push your changes to GitHub.
Go to Read the Docs. Sign up for an account if you don’t have one.
Import the project.
Enter the details of your project in the
repo
field and hitCreate
.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 <../contribute/development_workflow to the master
branch of the NEST Source Code Repository. Your pull request will be reviewed
by the NEST Documentation Team!