README.md

NEURON Documentation

Online

Latest NEURON documentation is available on:

• ReadTheDocs @ https://nrn.readthedocs.io/en/latest/.

Contents:

• Documentation on building NEURON
• User documentation (HOC, Python, tutorials, rxd)
• Developer documentation (SCM, technical topics, Doxygen)

On pull requests

The documentation is built automatically as part of continuous integration (CI) when a pull request is opened, under the name docs/readthedocs.org:nrn. Upon success, it can viewed by clicking on the "Details" link to the right of the name. If the build fails, the logs will be available at the same link.

Local build

To build the NEURON documentation, one needs to install the same prerequisites as for building NEURON itself; see the install instructions for a complete list of build dependencies.

Virtual environment

It is recommended to use a Python virtual environment, for example:

python3 -m venv venv
source venv/bin/activate

In order to build documentation locally, you need to pip install the docs_requirements.txt :

pip3 install -r docs/docs_requirements.txt --upgrade

Also, make sure to have Doxygen and pandoc installed. On MacOS, you can install these packages using brew:

brew install doxygen pandoc

Configuring the build

With all dependencies installed, configure project with CMake (>= v3.17) as described in CMake Build Options.

e.g. in your CMake build folder:

cmake .. -DNRN_ENABLE_DOCS=ON

Building the documentation

In order to build the full documentation (Doxygen, Jupyter notebooks, Sphinx):

make docs

That will build everything in the nrn/docs/_build folder from where you can open index.html locally.

In case you just want the Sphinx build to be performed (i.e. you are not working on Jupyter notebooks or doxygen):

make sphinx

Faster Local Iterations

When working locally on documentation, depending on what you work on, be aware of the following targets to speed up building process:

• doxygen - build the API documentation only. Ends up in _generated folder under docs.
• notebooks - execute & embed outputs in-place into jupyter notebooks, see PythonNotebookHelper.cmake
• notebooks-clean - clears outputs from notebooks. Remember that executing notebooks will add outputs in-place, and we don't want those committed to the repo.
• sphinx - build Sphinx documentation

NOTE:

• docs target calls: doxygen notebooks sphinx.
• sphinx target is the one that will assemble all generated output (doxygen, notebooks).

ReadTheDocs setup

Config file

Configuration file is in the top directory: ../.readthedocs.yml.

Documentation not handled by RTD

For RTD we need to call doxygen and notebooks make targets, since only sphinx executable is called therein.

Leveraging conf.py

The only way to gather extra documentation in RTD is to make use of conf.py. Have a look at if os.environ.get("READTHEDOCS"): block in conf.py to see how we leverage the aforementioned targets and outputs.

New release on RTD

To create a new public release on RTD, follow these steps:

• create a new release (see GHA Neuron Release - Manual Workflow)
• publish the wheels (these will be pip-installed by RTD)
• go to NRN RTD Versions page and activate the new tag. Make sure that the version is not marked as hidden.

NOTE: builds can be re-launched as many times as needed