Merge pull request #2603 from jessica-mitchell/add-sphinx-mermaid

Add sphinx-mermaid extension and update userdoc workflow
nest · Sep 11, 2023 · 4cf76ce · 4cf76ce
2 parents 50403ee + 224ba79
commit 4cf76ce
Show file tree

Hide file tree

Showing 6 changed files with 172 additions and 89 deletions.
diff --git 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",
     "add_button_notebook",
     "IPython.sphinxext.ipython_console_highlighting",
@@ -88,6 +89,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/...eveloper_space/workflows/documentation_workflow/user_documentation_workflow.rst b/...eveloper_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 <https://www.sphinx-doc.org/en/master/>`_ to generate
 documentation and `Read the Docs <https://readthedocs.org/>`_ to
 publish it. Sphinx uses reStructuredText as the base format for the
 documentation. To learn more about the syntax, check out this `quick
 reference
-<https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html>`_.
+<https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_.
 
 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 <https://www.github.com>`_ 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 <https://github.com/nest/nest-simulator>`_ and create a `pull
+request <https://github.com/nest/nest-simulator/pulls>`_. 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
-   <devdoc_workflow>`.
+* Fork the nest-simulator repository (see :ref:`here <fork>` 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 <https://github.com/nest/nest-simulator/issues>`_ in
-our GitHub repository.
+.. code-block:: bash
 
-You can also make changes directly to your forked copy of the `NEST source
-code repository <https://github.com/nest/nest-simulator>`_ and create a `pull
-request <https://github.com/nest/nest-simulator/pulls>`_. Just follow the
-workflow below!
+   git clone git@github.com:<my-username>/nest-simulator
+
+* Create a branch to a make your changes
+
+.. code-block:: bash
+
+   git checkout -b <my-new-feature>
+
+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 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_.
 
-Rendering HTML
-~~~~~~~~~~~~~~
+Please see our :ref:`documentation style guide <doc_styleguide>` 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
+   <browser> ../_build/html/index.html
 
 .. tip::
 
@@ -123,61 +191,41 @@ commands.
        cmake -Dwith-userdoc=ON </path/to/NEST/src>
        make docs
 
-Editing and creating pages
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To edit existing `reStructuredText <https://thomas-cokelaer.info/tutorials/
-sphinx/rest_syntax.html>`_ 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 <https://help.github.com/articles/using-pull-requests/#initiating-the-pull-request>`_.
 
-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 <https://nest-simulator.readthedocs.io/en/latest/_downloads/9b65adbdacba6bfed66e68c62af4e308/NEST_Contributor_Agreement.pdf>`
+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 <doc_styleguide>` 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 <https://github.com/nest/nest-simulator/issues>`_ on
+   GitHub.
 
-3. Go to `Read the Docs <https://readthedocs.org/>`_. Sign up for an account
-   if you don't have one.
 
-4. `Import <https://readthedocs.org/dashboard/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
+   <devdoc_workflow>`.
 
-6. `Build <https://docs.readthedocs.io/en/stable/intro/
-   import-guide.html#building-your-documentation>`_ 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 <git_workflow>` to the ``master``
-branch of the NEST Source Code Repository. Your pull request will be reviewed
-by the NEST Documentation Team!
+See `this guide <https://docs.readthedocs.io/en/stable/intro/import-guide.htmli>`_
+for more information.
diff --git a/doc/htmldoc/static/css/custom.css b/doc/htmldoc/static/css/custom.css
@@ -96,6 +96,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 
@@ -175,15 +202,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
@@ -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
@@ -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 → pynest/examples/README.txt b/pynest/examples/README.rst → pynest/examples/README.txt