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