diff --git a/doc/htmldoc/conf.py b/doc/htmldoc/conf.py
index 18fa827ab0..69eb92acf2 100644
--- a/doc/htmldoc/conf.py
+++ b/doc/htmldoc/conf.py
@@ -53,6 +53,7 @@
"sphinx.ext.autosummary",
"sphinx.ext.doctest",
"sphinx.ext.intersphinx",
+ "sphinxcontrib.mermaid",
"sphinx.ext.mathjax",
"IPython.sphinxext.ipython_console_highlighting",
"nbsphinx",
@@ -87,6 +88,11 @@
# The output lines will not be copied if set to True
copybutton_only_copy_prompt_lines = True
+mermaid_output_format = "raw"
+mermaid_version = "10.2.0"
+
+# disable require js - mermaid doesn't work if require.js is loaded before it
+nbsphinx_requirejs_path = ""
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
diff --git a/doc/htmldoc/developer_space/workflows/documentation_workflow/user_documentation_workflow.rst b/doc/htmldoc/developer_space/workflows/documentation_workflow/user_documentation_workflow.rst
index 6be9783f6b..1b01b91fab 100644
--- a/doc/htmldoc/developer_space/workflows/documentation_workflow/user_documentation_workflow.rst
+++ b/doc/htmldoc/developer_space/workflows/documentation_workflow/user_documentation_workflow.rst
@@ -1,17 +1,17 @@
.. _userdoc_workflow:
User-level documentation workflow
-#################################
+=================================
-What you need to know
-+++++++++++++++++++++
+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
@@ -21,35 +21,73 @@ 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**.
+.. mermaid::
+ :zoom:
+ :caption: Overview of documentation build. Drag and zoom to explore.
+
+ 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
+
+
+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!
-.. image:: ../../../static/img/documentation_workflow.png
- :width: 500
- :alt: Alternative text
+If you have not done so alrealdy first
-.. note::
- This workflow shows you how to create **user-level documentation**
- for NEST. For the **developer documentation**, please refer to our
- :ref:`Developer documentation workflow
- `.
+* Fork the nest-simulator repository (see :ref:`here ` for details on first time setup)
-Changing the documentation
-++++++++++++++++++++++++++
+* Clone the nest-simulator:
-If you notice any errors or weaknesses in the documentation, please
-submit an `Issue `_ in
-our GitHub repository.
+.. code-block:: bash
-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!
+ git clone git@github.com:/nest-simulator
+
+* Create a branch to a make your changes
+
+.. code-block:: bash
+
+ git checkout -b
+
+Set up your environment
+~~~~~~~~~~~~~~~~~~~~~~~
-Setting up your environment
-+++++++++++++++++++++++++++
+Using the Conda package (includes everything to build NEST, including documentation)
+````````````````````````````````````````````````````````````````````````````````````
-We recommend that you set up a full NEST developer environment using
-Conda (for details on Conda, see :ref:`conda_tips`):
+For details on Conda, see :ref:`conda_tips`
.. code-block:: bash
@@ -64,6 +102,9 @@ 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:
@@ -78,41 +119,68 @@ If you use pip, install ``pandoc`` from your platform's package manager (e.g. ap
sudo apt-get install pandoc
-Generating documentation with Sphinx
-++++++++++++++++++++++++++++++++++++
+Edit and create pages
+~~~~~~~~~~~~~~~~~~~~~~
-Now that you activated your environment, you can generate HTML files using
-Sphinx.
+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 `_.
-Rendering HTML
-~~~~~~~~~~~~~~
+Please see our :ref:`documentation style guide ` for information on how to write good documentation in NEST.
-You can build and preview the documentation locally by running the following
-commands.
-1. Clone the NEST repository:
+Where to find documentation in the repository
+`````````````````````````````````````````````
-.. code-block:: bash
+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:
- git clone git@github.com:nest/nest-simulator
+.. list-table::
+ :header-rows: 1
-2. Navigate to the ``doc/htmldoc`` folder:
+ * - 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:
.. code-block:: bash
cd nest-simulator/doc/htmldoc
-3. Build the docs:
+#. Build the docs:
.. code-block:: bash
sphinx-build . ../_build/html -b html
-4. Preview files. They are located in ``doc/_build/html``
+#. Preview files. They are located in ``doc/_build/html``
.. code-block:: bash
- browser ../_build/html/index.html
+ ../_build/html/index.html
.. tip::
@@ -123,61 +191,41 @@ commands.
cmake -Dwith-userdoc=ON
make docs
-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/htmldoc`` directory using your
- editor of choice.
-2. If you create a new page, open ``index.rst`` in the ``doc/htmldoc`` directory
- and add the file name under ``.. toctree::``. This will ensure it appears on
- the NEST Simulator documentation's table of contents.
+Create a pull request
+~~~~~~~~~~~~~~~~~~~~~
-3. If you rename or move a file, please make sure you update all the
- corresponding cross-references.
+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 `_.
-4. Save your changes.
+Reviewers will be assigned and go through your changes.
-5. Re-render documentation as described above.
-
-.. note::
+If you are a first time contributor, we ask that you fill out the
+:download:`NEST Contributor Agreement `
+form to transfer your copyright to the NEST initiative and send it to *info [at] nest-initiative.org*.
- Please see our :ref:`documentation style guide ` for information on how to write good documentation in the NEST style.
-
-Proceed as follows to preview your version of the documentation on Read the
-Docs.
-
-1. Check that unwanted directories are listed in ``.gitignore``:
-
-.. code-block:: bash
-
- _build
- _static
- _templates
+.. tip::
-2. Add, commit and push your changes to GitHub.
+ If you notice any errors or weaknesses in the documentation, you can
+ also submit an `Issue `_ on
+ GitHub.
-3. Go to `Read the Docs `_. Sign up for an account
- if you don't have one.
-4. `Import `_ the project.
+.. seealso::
-5. Enter the details of your project in the ``repo`` field and hit ``Create``.
+ This workflow shows you how to create **user-level documentation**
+ for NEST. For the **developer documentation**, please refer to our
+ :ref:`Developer documentation workflow
+ `.
-6. `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.
+Read the Docs
+``````````````
-Creating pull request
-+++++++++++++++++++++
+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.
-Once your documentation work is finished, you can create a
-:ref:`pull request ` to the ``master``
-branch of the NEST Source Code Repository. Your pull request will be reviewed
-by the NEST Documentation Team!
+See `this guide `_
+for more information.
diff --git a/doc/htmldoc/static/css/custom.css b/doc/htmldoc/static/css/custom.css
index 272f6cfac9..bd83c02e2c 100644
--- a/doc/htmldoc/static/css/custom.css
+++ b/doc/htmldoc/static/css/custom.css
@@ -99,6 +99,33 @@ section#kernel-attributes-nest-nestmodule dd {
border-bottom: 1px solid #ddd;
}
+/*************************************************************
+ * Rules for mermaid diagrams
+ *************************************************************/
+
+.mermaid .cluster rect {
+ fill: #47555B21 !important;
+ stroke: None !important;
+ stroke-width: None !important;
+}
+
+
+rect.basic.label-container {
+ fill: #e2e2e200; !important
+ stroke: #ff6633;
+ stroke-width: 1px;
+}
+
+figure, .align-default {
+ text-align: center;
+}
+.mermaid svg {
+ /* outline: auto; */
+ outline-color: #f0f0f069;
+ outline-width: medium;
+ outline-style: groove;
+}
+
/**************************************************************************************
Settings for overriding material design theme
@@ -178,15 +205,15 @@ div.sd-card-title.sd-font-weight-bold.sd-d-flex-row.docutils a.reference.interna
}
-.md-typeset .admonition {
+.md-typeset .admonition, .md-typeset .admonition.tip {
border-left: .2rem solid var(--nest-blue);
border-radius: 5px;
}
-.md-typeset .admonition > .admonition-title::before, .md-typeset .admonition.important > .admonition-title::before {
+.md-typeset .admonition > .admonition-title::before, .md-typeset .admonition.important > .admonition-title::before, .md-typeset .admonition.tip > .admonition-title::before {
color: #fff;
}
-.md-typeset .admonition > .admonition-title{
+.md-typeset .admonition > .admonition-title, .md-typeset .admonition.tip > .admonition-title {
background-color: var(--nest-blue);
color: #fff;
}
diff --git a/doc/requirements.txt b/doc/requirements.txt
index 42f6a84549..d79960d6d0 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -31,6 +31,7 @@ sphinx-notfound-page>=0.8.3
sphinx-design==0.4.1
sphinx-gallery==0.13.0
sphinx-material==0.0.35
+sphinxcontrib-mermaid
statsmodels==0.13.5
tqdm==4.65.0
yamllint==1.31.0
diff --git a/environment.yml b/environment.yml
index 20bb2638e5..63fd2614a4 100644
--- a/environment.yml
+++ b/environment.yml
@@ -106,9 +106,10 @@ dependencies:
- example
- Image
- sphinx_autobuild
+ - sphinx-copybutton
- sphinx_gallery
- sphinx-tabs
- sphinx_design
- sphinx-material
- - sphinx-copybutton
- sphinx-notfound-page
+ - sphinxcontrib-mermaid
diff --git a/pynest/examples/README.rst b/pynest/examples/README.txt
similarity index 100%
rename from pynest/examples/README.rst
rename to pynest/examples/README.txt