Update documentation index page and navigation structure

doc/htmldoc/attribution-list.rst

@@ -26,3 +26,5 @@ Icons provided by Flaticon
 <a href="https://www.flaticon.com/free-icons/quote" title="quote icons">Quote icons created by DinosoftLabs - Flaticon</a>
 <a href="https://www.flaticon.com/free-icons/mail" title="mail icons">Mail icons created by Freepik - Flaticon</a>
 <a href="https://www.flaticon.com/free-icons/external-link" title="external link icons">External link icons created by Bharat Icons - Flaticon</a>
+<a href="https://www.flaticon.com/free-icons/start-icon" title="start icon icons">Start icon icons created by Creative Squad - Flaticon</a>
+<a href="https://www.flaticon.com/free-icons/source-code" title="source code icons">Source code icons created by Pixel perfect - Flaticon</a>

doc/htmldoc/conf.py

@@ -44,6 +44,7 @@
 source_suffix = ".rst"
 master_doc = "index"
 extensions = [
+    "hoverxref.extension",
     "sphinx_gallery.gen_gallery",
     "list_examples",
     "sphinx.ext.autodoc",
@@ -53,26 +54,26 @@
     "sphinx.ext.intersphinx",
     "sphinxcontrib.mermaid",
     "sphinx.ext.mathjax",
+    "sphinx_carousel.carousel",
     "sphinxcontrib.plantuml",
     "add_button_notebook",
     "IPython.sphinxext.ipython_console_highlighting",
     "nbsphinx",
     "extract_api_functions",
     "sphinx_design",
-    "HoverXTooltip",
     "VersionSyncRole",
     "sphinx_copybutton",
     "notfound.extension",
 ]
 
 autodoc_mock_imports = ["nest.pynestkernel", "nest.ll_api"]
 mathjax_path = "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"
-panels_add_bootstrap_css = False
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["templates"]
 
 # To run plantuml locally see the user documentation workflow
 plantuml = "java -jar /tmp/plantuml.jar"
+plantuml_output_format = "svg_img"
 sphinx_gallery_conf = {
     # path to your examples scripts
     "examples_dirs": "../../pynest/examples",
@@ -82,6 +83,9 @@
     "download_all_examples": False,
 }
 
+carousel_show_captions_below = True
+# carousel_show_controls = True
+
 # General information about the project.
 project = "NEST Simulator user documentation"
 copyright = "2004, nest-simulator"
@@ -177,7 +181,18 @@
 }
 
 html_static_path = ["static"]
-html_additional_pages = {"index": "index.html"}
+
+html_css_files = [
+    "css/custom.css",
+    "css/popup.css",
+    "css/pygments.css",
+]
+
+html_js_files = [
+    "js/custom.js",
+    "js/popup.js",
+]
+# html_additional_pages = {"index": "index.html"}
 html_sidebars = {"**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]}
 
 html_favicon = "static/img/nest_favicon.ico"
@@ -230,9 +245,6 @@ def setup(app):
     # for events see
     # https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events
     app.connect("source-read", toc_customizer)
-    app.add_css_file("css/custom.css")
-    app.add_css_file("css/pygments.css")
-    app.add_js_file("js/custom.js")
     app.connect("config-inited", config_inited_handler)
 
 

doc/htmldoc/contribute.rst

@@ -0,0 +1,61 @@
+.. _contribute:
+
+Contribute to NEST
+==================
+
+NEST draws its strength from the many people that use and improve it. We
+are happy to consider your contributions (e.g., new models, bug or
+documentation fixes) for addition to the official version of NEST.
+
+Please familiarize yourself with our guides and workflows:
+
+
+
+.. grid:: 1 1 2 2
+
+    .. grid-item-card:: Mailing list
+
+      Have a question or problem about NEST? Get help from the NEST community:
+      use our :ref:`mailing list <mail_guidelines>`.
+
+    .. grid-item-card:: Create a GitHub issue
+
+      If you have a feature request, bug report or other issue, create
+      an issue on GitHub using `the templates <https://github.com/nest/nest-simulator/issues/new/choose>`_
+
+
+.. admonition:: First time contributors
+
+   In order to make sure that the NEST Initiative can manage the NEST code base in the long term,
+   we ask that you fill in 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*.
+
+
+
+
+.. grid:: 1 1 2 2
+
+    .. grid-item-card:: Contribute code
+
+       * New to git or need a refresher? See our :ref:`NEST git workflow <git_workflow>`
+       * Follow the :ref:`C++ coding style guidelines <code_style_cpp>`
+       * Review the :ref:`naming conventions for NEST <naming_conventions>`
+       * Writing an extension to NEST? See :doc:`extmod:index`
+       * :ref:`required_dev_tools` to ensure correct formatting
+
+    .. grid-item-card:: Contribute documentation
+
+       * See our documentation workflows for :ref:`user facing docs <userdoc_workflow>` and :ref:`technical docs <devdoc_workflow>`
+       * For making changes to the PyNEST APIs, see our :ref:`pyapi_template`
+       * If you have a Python example network to contribute, please refer to our
+         :ref:`pyexample_template`
+
+.. admonition:: Adding models to NEST
+
+    If you are looking at creating a new model, please consider :doc:`NESTML <nestml:index>`:
+    a modeling language supporting neuron and synapse specification, based on the syntax of Python.
+
+
+.. seealso::
+
+   You can find additional guides for technical documentation :ref:`here <developer_space>`

doc/htmldoc/developer_space/guidelines/styleguide/styleguide.rst

@@ -7,7 +7,7 @@ Why do we have a style guide?
 -----------------------------
 
 This style guide was created to provide a single reference point for content
-creation in NEST. This helps ensure the NEST user-level documentation remains
+creation in NEST. This helps ensure the NEST user facing documentation remains
 clear and consistent. The style choices we make here are meant to follow the
 major trends in technical writing for software.
 

doc/htmldoc/developer_space/index.rst

@@ -1,14 +1,14 @@
 .. _developer_space:
 
-Developer space
-===============
+Technical documentation
+=======================
 
 Here is all documentation pertaining to the development of NEST.
 It is documentation for anyone needing to touch the code or documentation.
 
-.. grid:: 3 
+.. grid:: 3
 
-  .. grid-item-card:: 
+  .. grid-item-card::
        :link-type: ref
        :link: dev_install
        :class-card: sd-bg-success sd-text-white
@@ -17,76 +17,27 @@ It is documentation for anyone needing to touch the code or documentation.
 
 
 
-.. _contribute:
+Guidelines and workflows for developing NEST
+---------------------------------------------
 
-Contribute to NEST
-------------------
 
-NEST draws its strength from the many people that use and improve it. We
-are happy to consider your contributions (e.g., new models, bug or
-documentation fixes) for addition to the official version of NEST.
 
-Please familiarize yourself with our guides and workflows:
+.. note::
 
+   Most of the guides and workflows for contributing to NEST can be found in our :ref:`contribute` guide.
 
 
-.. grid:: 1 1 2 2
-
-    .. grid-item-card:: Mailing list
-
-      Have a question or problem about NEST? Get help from the NEST community:
-      use our :ref:`mailing list <mail_guidelines>`.
-
-    .. grid-item-card:: Create a GitHub issue
-
-      If you have a feature request, bug report or other issue, create
-      an issue on GitHub using `the templates <https://github.com/nest/nest-simulator/issues/new/choose>`_
-
-
-.. grid:: 1 1 2 2
-
-    .. grid-item-card:: Contribute code
-
-       * New to git or need a refresher? See our :ref:`NEST git workflow <git_workflow>`
-       * Follow the :ref:`C++ coding style guidelines <code_style_cpp>`
-       * Review the :ref:`naming conventions for NEST <naming_conventions>`
-       * Writing an extension module? See :doc:`extmod:index`
-       * :ref:`required_dev_tools`
-
-    .. grid-item-card:: Contribute documentation
-
-       * Review the :ref:`documentation style guide <doc_styleguide>`
-       * For making changes to the PyNEST APIs, see our :ref:`pyapi_template`
-       * If you have a Python example network to contribute, please refer to our
-         :ref:`pyexample_template`
-       * Check that documentation renders properly: See the :ref:`build documentation <doc_workflow>` guide for developer and user documentation
-
-.. note:: Adding models to NEST
-
-    If you are looking at creating a new model, please check out :doc:`NESTML <nestml:index>`:
-    a modeling language supporting neuron and synapse specification, based on the syntax of Python.
-
-In order to make sure that the NEST Initiative can manage the NEST code base in the long term,
-you need to send us a completed and signed
-:download:`NEST Contributor Agreement <static/NEST_Contributor_Agreement.pdf>` to transfer your
-copyright to the NEST Initiative before we can merge your pull request.
-
-----
-
-Developer guides
-----------------
 
 .. grid:: 1 1 2 2
 
-    .. grid-item-card:: Reviewer guidelines
+   .. grid-item-card:: Reviewer guidelines
 
-        If you are requested to review a pull request, please
-        check our :ref:`code_guidelines`
+       * If you are requested to review a pull request, please check our :ref:`code_guidelines`
 
+   .. grid-item-card:: CI Workflow
 
-    .. grid-item-card::  Continuous integration
+       * Here you can find details on our :ref:`CI workflow <cont_integration>`
 
-        * Here you can find details on our :ref:`CI workflow <cont_integration>`
 
 .. grid:: 1 1 2 2
 
@@ -112,7 +63,7 @@ Developer guides
 
 .. toctree::
    :maxdepth: 1
-   :hidden: 
+   :hidden:
    :glob:
 
    workflows/*

doc/htmldoc/developer_space/workflows/documentation_workflow/developer_documentation_workflow.rst

@@ -1,10 +1,10 @@
 .. _devdoc_workflow:
 
-Developer documentation workflow
-################################
+Techincal documentation workflow
+================================
 
 What you need to know
-+++++++++++++++++++++
+---------------------
 
 For developer documentation, we use `Doxygen <http://doxygen.org/>`__
 comments extensively throughout NEST.
@@ -15,12 +15,12 @@ generated in the ``doc`` folder in your source directory.
 
 .. note::
 
-   This workflow shows you how to create **developer documentation**
-   for NEST. For the **user documentation**, please refer to our
-   :ref:`User documentation workflow <userdoc_workflow>`.
+   This workflow shows you how to create **technical documentation**
+   for NEST. For the **user facing documentation**, please refer to our
+   :ref:`User facing documentation workflow <userdoc_workflow>`.
 
 Instructions
-++++++++++++
+------------
 
 1. Install Doxygen and graphviz.
 

doc/htmldoc/developer_space/workflows/documentation_workflow/index.rst

@@ -8,6 +8,5 @@ Select the documentation workflow you would like to view:
 .. toctree::
     :maxdepth: 1
 
-    User-level documentation<user_documentation_workflow>
-    Developer documentation<developer_documentation_workflow>
-
+    User facing documentation<user_documentation_workflow>
+    Technical documentation<developer_documentation_workflow>

doc/htmldoc/developer_space/workflows/documentation_workflow/user_documentation_workflow.rst

@@ -1,7 +1,7 @@
 .. _userdoc_workflow:
 
-User-level documentation workflow
-=================================
+User facing documentation workflow
+==================================
 
 Overview of workflow
 --------------------
@@ -231,9 +231,9 @@ form to transfer your copyright to the NEST initiative and send it to *info [at]
 
 .. seealso::
 
-   This workflow shows you how to create **user-level documentation**
-   for NEST. For the **developer documentation**, please refer to our
-   :ref:`Developer documentation workflow
+   This workflow shows you how to create **user facing documentation**
+   for NEST. For the **technical documentation**, please refer to our
+   :ref:`Technical documentation workflow
    <devdoc_workflow>`.
 
 

doc/htmldoc/devices/index.rst

@@ -1,10 +1,29 @@
 .. _device_index:
 
-All about devices in NEST
-=========================
+All about recording and stimulating networks in NEST
+====================================================
+
+
+
+.. grid:: 1 1 2 2
+
+   .. grid-item-card:: |device| All about devices
+       :class-title: sd-d-flex-row sd-align-minor-center
+
+       * :ref:`record_simulations`
+
+       * :ref:`stimulate_network`
+
+   .. grid-item-card:: |math| Device models
+        :class-title: sd-d-flex-row sd-align-minor-center
+
+        * :doc:`/models/index_device`
 
 .. toctree::
   :maxdepth: 1
   :glob:
+  :hidden:
 
   *
+.. |math|  image:: ../static/img/math_orange128.svg
+.. |device|  image:: ../static/img/device_orange128.svg