nest · terhorstd · May 10, 2022 · Oct 19, 2021 · Oct 20, 2021 · Oct 20, 2021
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -2,7 +2,7 @@ version: 2
 
 sphinx:
   builder: html
-  configuration: doc/userdoc/conf.py
+  configuration: doc/htmldoc/conf.py
 
 python:
    version: 3.8

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -58,7 +58,7 @@ We review each pull request according to our [code review guidelines](https://ne
 
 ## Submitting Changes
 
-* Sign the [Contributor License Agreement](https://raw.githubusercontent.com/nest/nest-simulator/master/doc/userdoc/contribute/NEST_Contributor_Agreement.pdf).
+* Sign the [Contributor License Agreement](https://raw.githubusercontent.com/nest/nest-simulator/master/doc/htmldoc/contribute/NEST_Contributor_Agreement.pdf).
 * Push your changes to a topic branch in your fork of the repository.
 * Submit a pull request to the [NEST repository](https://github.com/nest/nest-simulator).
 * If your pull request affects documented issues, [mention](https://github.com/blog/957-introducing-issue-mentions) them in the description. If it is solving an issue, you can [state this explicitly](https://help.github.com/articles/closing-issues-via-commit-messages/).

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
@@ -90,8 +90,8 @@ else ()
   set( OUT_OF_TREE_BUILD "True" )
 endif ()
 
-set( DOC_BUILD_DIR "${PROJECT_BINARY_DIR}/doc/userdoc" )
-set( DOC_SOURCE_DIR "${PROJECT_SOURCE_DIR}/doc/userdoc" )
+set( DOC_BUILD_DIR "${PROJECT_BINARY_DIR}/doc/htmldoc" )
+set( DOC_SOURCE_DIR "${PROJECT_SOURCE_DIR}/doc/htmldoc" )
 
 add_custom_target( html
   COMMAND [ "${OUT_OF_TREE_BUILD}" = "True" ] && rm -rf "${DOC_BUILD_DIR}" || true

diff --git a/doc/userdoc/_ext/HoverXTooltip.py → doc/htmldoc/_ext/HoverXTooltip.py b/doc/userdoc/_ext/HoverXTooltip.py → doc/htmldoc/_ext/HoverXTooltip.py
@@ -143,7 +143,7 @@ def role(name, rawtext, text, lineno, inliner, options={}, content=[]):
         # for rtd builds
         if os.environ.get("READTHEDOCS") == "True":
             branch_name = base_url.split('/doc/')[0].split('/')[-1]
-            refuri = (f'/en/{branch_name}/glossary.html#term-{term}')
+            refuri = (f'/en/{branch_name}/ref_material/glossary.html#term-{term}')
         # for local builds
         else:
             refuri = base_url.split('userdoc')[0] + f'userdoc/html/glossary.html#term-{term}'
@@ -209,7 +209,7 @@ def get_desc_from_glossary(term):
     """
 
     try:
-        with open(str(doc_build_dir) + '/glossary.rst') as f:
+        with open(str(doc_build_dir) + '/ref_material/glossary.rst') as f:
             file_content = f.read()
 
         # generate a list of lines from file content.

diff --git a/doc/userdoc/_ext/VersionSyncRole.py → doc/htmldoc/_ext/VersionSyncRole.py b/doc/userdoc/_ext/VersionSyncRole.py → doc/htmldoc/_ext/VersionSyncRole.py
diff --git a/doc/userdoc/_ext/versions.json → doc/htmldoc/_ext/versions.json b/doc/userdoc/_ext/versions.json → doc/htmldoc/_ext/versions.json
diff --git a/doc/userdoc/citing-nest.rst → doc/htmldoc/citing-nest.rst b/doc/userdoc/citing-nest.rst → doc/htmldoc/citing-nest.rst
@@ -1,5 +1,3 @@
-:orphan:
-
 .. _cite_nest:
 
 Cite NEST

diff --git a/doc/userdoc/colorize.rst → doc/htmldoc/colorize.rst b/doc/userdoc/colorize.rst → doc/htmldoc/colorize.rst
diff --git a/doc/userdoc/community.rst → doc/htmldoc/community.rst b/doc/userdoc/community.rst → doc/htmldoc/community.rst
@@ -1,7 +1,7 @@
 .. _community:
 
-NEST Community
-==============
+Contact us
+==========
 
 Mailing list
 ------------
@@ -16,6 +16,12 @@ By subscribing to the mailing list you will also get notified of all NEST relate
 
 Before submitting a question, please take a look at our :ref:`guidelines for the NEST mailing list <mail_guidelines>`.
 
+Submit an issue or pull request on Github
+-----------------------------------------
+
+You can :ref:`issues` on Github or contribute to the code or documentation. See our :ref:`contribute` page for
+details.
+
 Open video conference
 ---------------------
 
@@ -25,20 +31,4 @@ This is an opportunity to have discussions in real time with developers.
 
 Information for dates and how to join can be found on `our GitHub wiki <https://github.com/nest/nest-simulator/wiki/Open-NEST-Developer-Video-Conference>`_
 
-Publications using NEST
------------------------
-
-We have compiled  a `list of NEST-related peer-reviewed publications <https://www.nest-simulator.org/publications/>`_ that
-we update regularly.
-
-If you have used NEST in your research, let us know!
-Don't forget to :ref:`cite NEST <cite_nest>` in your work.
-
-Have a talk or poster where you used NEST? `Download our logo  <https://github.com/nest/nest-simulator/tree/master/doc/logos>`_!
-
-Become a NEST member
---------------------
-
-If you would like to be actively involved in the NEST Initiative and support its
-goals, please see our `member page <https://www.nest-initiative.org/membership>`_.
 
diff --git a/doc/userdoc/conf.py → doc/htmldoc/conf.py b/doc/userdoc/conf.py → doc/htmldoc/conf.py
@@ -44,9 +44,9 @@
 
 
 if os.environ.get("READTHEDOCS") == "True":
-    doc_build_dir = source_dir / "doc/userdoc"
+    doc_build_dir = source_dir / "doc/htmldoc"
 else:
-    doc_build_dir = Path(os.environ["OLDPWD"]) / "doc/userdoc"
+    doc_build_dir = Path(os.environ["OLDPWD"]) / "doc/htmldoc"
 
 sys.path.append(os.path.abspath("./_ext"))
 

diff --git a/doc/htmldoc/connect_nest/index.rst b/doc/htmldoc/connect_nest/index.rst
@@ -0,0 +1,11 @@
+.. _connect_index:
+
+Connect NEST with other tools
+=============================
+
+
+.. toctree::
+    :maxdepth: 1
+
+    nest_server
+    using_nest_with_music
diff --git a/doc/userdoc/nest_server.rst → doc/htmldoc/connect_nest/nest_server.rst b/doc/userdoc/nest_server.rst → doc/htmldoc/connect_nest/nest_server.rst
diff --git a/doc/userdoc/guides/using_nest_with_music.rst → ...oc/connect_nest/using_nest_with_music.rst b/doc/userdoc/guides/using_nest_with_music.rst → ...oc/connect_nest/using_nest_with_music.rst
diff --git a/doc/htmldoc/contents.rst b/doc/htmldoc/contents.rst
@@ -0,0 +1,56 @@
+Table of Contents
+=================
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Get started
+
+   Install NEST <installation/index>
+   tutorials/index
+   PyNEST example scripts <examples/index>
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Understand how NEST works
+
+   NEST models <models/models-main>
+   Neurons <neurons/index>
+   Synapses and connections <synapses/index>
+   Devices  <devices/index>
+   Spatially-structured networks <networks/spatially_structured_networks>
+   Simulation behavior <nest_behavior/running_simulations>
+   Randomness in NEST <nest_behavior/random_numbers>
+   Built-in timers <nest_behavior/built-in_timers>
+   Connect NEST with other tools <connect_nest/index>
+   Parallel computing <hpc/parallel_computing>
+   Benchmarking <hpc/benchmarking>
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Reference material
+
+   Release notes <release_notes/index>
+   ref_material/pynest_apis
+   Model directory <models/index>
+   From NEST 2.x to 3.x <release_notes/v3.0/refguide_nest2_nest3>
+   Glossary <ref_material/glossary>
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Community
+
+   Get help <getting_help>
+   Contact us <community>
+   Contribute <developer_space/contribute>
+   Cite NEST <citing-nest>
+   Developer space <developer_space/index>
+   related_projects
+   News and updates <https://nest-simulator.org>
+   Publications <https://www.nest-simulator.org/publications/>
+   NEST Initiative <https://www.nest-initiative.org/>
+   license
+
+
diff --git a/doc/userdoc/contribute/index.rst → doc/htmldoc/developer_space/contribute.rst b/doc/userdoc/contribute/index.rst → doc/htmldoc/developer_space/contribute.rst
@@ -1,7 +1,7 @@
 .. _contribute:
 
-Contributing to 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
@@ -19,6 +19,8 @@ you need to send us a completed and signed
 :download:`NEST Contributor Agreement <NEST_Contributor_Agreement.pdf>` to transfer your
 copyright to the NEST Initiative before we can merge your pull request.
 
+.. _issues:
+
 Report bugs and request features
 --------------------------------
 
@@ -71,3 +73,5 @@ Have a question?
 ----------------
 
 If you want to get in contact with us, see our :ref:`community` page for ways you can reach us.
+
+
diff --git a/...doc/contribute/code_review_guidelines.rst → ...ace/guidelines/code_review_guidelines.rst b/...doc/contribute/code_review_guidelines.rst → ...ace/guidelines/code_review_guidelines.rst
diff --git a/...oc/contribute/coding_guidelines_check.rst → ...ce/guidelines/coding_guidelines_check.rst b/...oc/contribute/coding_guidelines_check.rst → ...ce/guidelines/coding_guidelines_check.rst
diff --git a/...rdoc/contribute/coding_guidelines_cpp.rst → ...pace/guidelines/coding_guidelines_cpp.rst b/...rdoc/contribute/coding_guidelines_cpp.rst → ...pace/guidelines/coding_guidelines_cpp.rst
diff --git a/...oc/contribute/mailing_list_guidelines.rst → ...ce/guidelines/mailing_list_guidelines.rst b/...oc/contribute/mailing_list_guidelines.rst → ...ce/guidelines/mailing_list_guidelines.rst
diff --git a/...userdoc/contribute/naming_conventions.rst → ...r_space/guidelines/naming_conventions.rst b/...userdoc/contribute/naming_conventions.rst → ...r_space/guidelines/naming_conventions.rst
diff --git a/...rdoc/contribute/styleguide/sample_doc.rst → ...pace/guidelines/styleguide/sample_doc.rst b/...rdoc/contribute/styleguide/sample_doc.rst → ...pace/guidelines/styleguide/sample_doc.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. _sample_doc:
 
 Main title of document

diff --git a/...rdoc/contribute/styleguide/styleguide.rst → ...pace/guidelines/styleguide/styleguide.rst b/...rdoc/contribute/styleguide/styleguide.rst → ...pace/guidelines/styleguide/styleguide.rst
diff --git a/...contribute/styleguide/vim_support_sli.rst → ...guidelines/styleguide/vim_support_sli.rst b/...contribute/styleguide/vim_support_sli.rst → ...guidelines/styleguide/vim_support_sli.rst
diff --git a/doc/htmldoc/developer_space/index.rst b/doc/htmldoc/developer_space/index.rst
@@ -0,0 +1,53 @@
+.. _developer_space:
+
+Developer space
+===============
+
+Here is all documentation pertaining to the development of NEST.
+It is documentation for anyone needing to touch the code or documentation (also includes SLI, since it is more complex
+and likely used by developers or very advanced users).
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Install from source
+
+   ../installation/linux_install
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Workflows
+   :glob:
+
+   workflows/*
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Guidelines
+   :glob:
+
+   guidelines/*
+   guidelines/styleguide/styleguide
+   guidelines/styleguide/vim_support_sli
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Templates
+   :glob:
+
+   templates/*
+
+.. toctree::
+   :maxdepth: 1
+   :caption: SLI docs
+   :glob:
+
+   sli_docs/index
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Doxygen output
+
+   doxygen/
diff --git a/...erdoc/sli_docs/an-introduction-to-sli.rst → ...space/sli_docs/an-introduction-to-sli.rst b/...erdoc/sli_docs/an-introduction-to-sli.rst → ...space/sli_docs/an-introduction-to-sli.rst
diff --git a/doc/userdoc/sli_docs/first-steps.rst → .../developer_space/sli_docs/first-steps.rst b/doc/userdoc/sli_docs/first-steps.rst → .../developer_space/sli_docs/first-steps.rst
diff --git a/doc/htmldoc/developer_space/sli_docs/index.rst b/doc/htmldoc/developer_space/sli_docs/index.rst
@@ -0,0 +1,16 @@
+.. _sli_doc:
+
+SLI documentation
+=================
+
+
+.. toctree::
+   :maxdepth: 1
+
+   an-introduction-to-sli
+   first-steps
+   neural-simulations
+   objects-and-data-types
+   programming-in-sli
+   using-files-and-keyboard-input
+
diff --git a/doc/userdoc/sli_docs/neural-simulations.rst → ...per_space/sli_docs/neural-simulations.rst b/doc/userdoc/sli_docs/neural-simulations.rst → ...per_space/sli_docs/neural-simulations.rst
diff --git a/...erdoc/sli_docs/objects-and-data-types.rst → ...space/sli_docs/objects-and-data-types.rst b/...erdoc/sli_docs/objects-and-data-types.rst → ...space/sli_docs/objects-and-data-types.rst
diff --git a/doc/userdoc/sli_docs/programming-in-sli.rst → ...per_space/sli_docs/programming-in-sli.rst b/doc/userdoc/sli_docs/programming-in-sli.rst → ...per_space/sli_docs/programming-in-sli.rst
diff --git a/...i_docs/using-files-and-keyboard-input.rst → ...i_docs/using-files-and-keyboard-input.rst b/...i_docs/using-files-and-keyboard-input.rst → ...i_docs/using-files-and-keyboard-input.rst
diff --git a/...contribute/NEST_Contributor_Agreement.pdf → ...ace/static/NEST_Contributor_Agreement.pdf b/...contribute/NEST_Contributor_Agreement.pdf → ...ace/static/NEST_Contributor_Agreement.pdf
diff --git a/...state_machine_communication_with_Nest.svg → ...state_machine_communication_with_Nest.svg b/...state_machine_communication_with_Nest.svg → ...state_machine_communication_with_Nest.svg
diff --git a/...MPI_backend_protocol_of_communication.svg → ...MPI_backend_protocol_of_communication.svg b/...MPI_backend_protocol_of_communication.svg → ...MPI_backend_protocol_of_communication.svg
diff --git a/...doc/static/img/MPI_backend_state_Nest.svg → ...ace/static/img/MPI_backend_state_Nest.svg b/...doc/static/img/MPI_backend_state_Nest.svg → ...ace/static/img/MPI_backend_state_Nest.svg
diff --git a/...state_machine_communication_with_Nest.uxf → ...state_machine_communication_with_Nest.uxf b/...state_machine_communication_with_Nest.uxf → ...state_machine_communication_with_Nest.uxf
diff --git a/...MPI_backend_protocol_of_communication.uxf → ...MPI_backend_protocol_of_communication.uxf b/...MPI_backend_protocol_of_communication.uxf → ...MPI_backend_protocol_of_communication.uxf
diff --git a/...c/static/ulmet/MPI_backend_state_Nest.uxf → ...e/static/ulmet/MPI_backend_state_Nest.uxf b/...c/static/ulmet/MPI_backend_state_Nest.uxf → ...e/static/ulmet/MPI_backend_state_Nest.uxf
diff --git a/...contribute/templates/example_template.rst → ...oper_space/templates/example_template.rst b/...contribute/templates/example_template.rst → ...oper_space/templates/example_template.rst
diff --git a/...c/contribute/templates/pyapi_template.rst → ...eloper_space/templates/pyapi_template.rst b/...c/contribute/templates/pyapi_template.rst → ...eloper_space/templates/pyapi_template.rst
diff --git a/...ntribute/templates/pynest_api_template.py → ...er_space/templates/pynest_api_template.py b/...ntribute/templates/pynest_api_template.py → ...er_space/templates/pynest_api_template.py
diff --git a/...bute/templates/pynest_example_template.py → ...pace/templates/pynest_example_template.py b/...bute/templates/pynest_example_template.py → ...pace/templates/pynest_example_template.py
diff --git a/doc/userdoc/contribute/ci.rst → doc/htmldoc/developer_space/workflows/ci.rst b/doc/userdoc/contribute/ci.rst → doc/htmldoc/developer_space/workflows/ci.rst
diff --git a/...erdoc/contribute/development_workflow.rst → ..._space/workflows/development_workflow.rst b/...erdoc/contribute/development_workflow.rst → ..._space/workflows/development_workflow.rst
diff --git a/...flow/developer_documentation_workflow.rst → ...flow/developer_documentation_workflow.rst b/...flow/developer_documentation_workflow.rst → ...flow/developer_documentation_workflow.rst
diff --git a/doc/userdoc/documentation_workflow/index.rst → ...orkflows/documentation_workflow/index.rst b/doc/userdoc/documentation_workflow/index.rst → ...orkflows/documentation_workflow/index.rst
diff --git a/..._workflow/user_documentation_workflow.rst → ..._workflow/user_documentation_workflow.rst b/..._workflow/user_documentation_workflow.rst → ..._workflow/user_documentation_workflow.rst
@@ -14,7 +14,7 @@ reference
 <https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html>`_.
 
 The NEST simulator documentation lives alongside its code. It is
-contained in the ``doc/userdoc`` directory within the `NEST source
+contained in the ``doc/htmldoc`` directory within the `NEST source
 code repository <https://github.com/nest/nest-simulator>`_ on GitHub.
 
 We work with `GitHub <https://www.github.com>`_ as a web-based hosting
@@ -97,11 +97,11 @@ directory where you ran ``cmake``)
 
    make html
 
-3. Preview files. They are located in ``doc/userdoc/html``
+3. Preview files. They are located in ``doc/htmldoc/html``
 
 .. code-block:: bash
 
-   browser doc/userdoc/html/index.html
+   browser doc/htmldoc/html/index.html
 
 To install the documentation under ``<nest_install_dir>`` along with
 the rest of NEST, the ``make html`` command can be followed by
@@ -122,10 +122,10 @@ 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/userdoc`` directory using your
+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 ``contents.rst`` in the ``doc/userdoc`` directory
+2. If you create a new page, open ``contents.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.
 

diff --git a/doc/userdoc/contribute/nest_with_ides.rst → ...eloper_space/workflows/nest_with_ides.rst b/doc/userdoc/contribute/nest_with_ides.rst → ...eloper_space/workflows/nest_with_ides.rst
diff --git a/doc/htmldoc/devices/index.rst b/doc/htmldoc/devices/index.rst
@@ -0,0 +1,10 @@
+.. _device_index:
+
+All about devices in NEST
+=========================
+
+.. toctree::
+  :maxdepth: 1
+  :glob:
+
+  *
diff --git a/...serdoc/guides/record_from_simulations.rst → ...mldoc/devices/record_from_simulations.rst b/...serdoc/guides/record_from_simulations.rst → ...mldoc/devices/record_from_simulations.rst
diff --git a/doc/userdoc/guides/stimulate_the_network.rst → ...htmldoc/devices/stimulate_the_network.rst b/doc/userdoc/guides/stimulate_the_network.rst → ...htmldoc/devices/stimulate_the_network.rst
diff --git a/doc/userdoc/download.rst → doc/htmldoc/download.rst b/doc/userdoc/download.rst → doc/htmldoc/download.rst
diff --git a/...serdoc/examples/cortical_microcircuit.rst → ...tmldoc/examples/cortical_microcircuit.rst b/...serdoc/examples/cortical_microcircuit.rst → ...tmldoc/examples/cortical_microcircuit.rst
diff --git a/.../examples/cortical_microcircuit_index.rst → .../examples/cortical_microcircuit_index.rst b/.../examples/cortical_microcircuit_index.rst → .../examples/cortical_microcircuit_index.rst
diff --git a/doc/userdoc/examples/index.rst → doc/htmldoc/examples/index.rst b/doc/userdoc/examples/index.rst → doc/htmldoc/examples/index.rst
diff --git a/doc/userdoc/faqs/faqs.rst → doc/htmldoc/faqs/faqs.rst b/doc/userdoc/faqs/faqs.rst → doc/htmldoc/faqs/faqs.rst
diff --git a/doc/userdoc/faqs/index.rst → doc/htmldoc/faqs/index.rst b/doc/userdoc/faqs/index.rst → doc/htmldoc/faqs/index.rst
diff --git a/doc/userdoc/faqs/qa-precise-spike-times.rst → doc/htmldoc/faqs/qa-precise-spike-times.rst b/doc/userdoc/faqs/qa-precise-spike-times.rst → doc/htmldoc/faqs/qa-precise-spike-times.rst
diff --git a/doc/userdoc/features.rst → doc/htmldoc/features.rst b/doc/userdoc/features.rst → doc/htmldoc/features.rst
diff --git a/doc/userdoc/getting_help.rst → doc/htmldoc/getting_help.rst b/doc/userdoc/getting_help.rst → doc/htmldoc/getting_help.rst
diff --git a/doc/userdoc/getting_started.rst → doc/htmldoc/getting_started.rst b/doc/userdoc/getting_started.rst → doc/htmldoc/getting_started.rst
diff --git a/doc/htmldoc/hpc/index.rst b/doc/htmldoc/hpc/index.rst
@@ -0,0 +1,14 @@
+.. _hpc_index:
+
+All about high performance computing
+====================================
+
+.. toctree::
+  :maxdepth: 1
+  :glob:
+
+  *
+
+.. todo::
+
+   Add pinning threads and benchmarking documentation here.
diff --git a/doc/userdoc/guides/parallel_computing.rst → doc/htmldoc/hpc/parallel_computing.rst b/doc/userdoc/guides/parallel_computing.rst → doc/htmldoc/hpc/parallel_computing.rst
diff --git a/doc/userdoc/img/All_to_all.png → doc/htmldoc/img/All_to_all.png b/doc/userdoc/img/All_to_all.png → doc/htmldoc/img/All_to_all.png
diff --git a/doc/userdoc/img/Convergent_connect.png → doc/htmldoc/img/Convergent_connect.png b/doc/userdoc/img/Convergent_connect.png → doc/htmldoc/img/Convergent_connect.png
diff --git a/doc/userdoc/img/Divergent_connect.png → doc/htmldoc/img/Divergent_connect.png b/doc/userdoc/img/Divergent_connect.png → doc/htmldoc/img/Divergent_connect.png
diff --git a/doc/userdoc/img/Fixed_indegree.png → doc/htmldoc/img/Fixed_indegree.png b/doc/userdoc/img/Fixed_indegree.png → doc/htmldoc/img/Fixed_indegree.png
diff --git a/doc/userdoc/img/Fixed_outdegree.png → doc/htmldoc/img/Fixed_outdegree.png b/doc/userdoc/img/Fixed_outdegree.png → doc/htmldoc/img/Fixed_outdegree.png
diff --git a/doc/userdoc/img/MultimeterExample.png → doc/htmldoc/img/MultimeterExample.png b/doc/userdoc/img/MultimeterExample.png → doc/htmldoc/img/MultimeterExample.png
diff --git a/doc/userdoc/img/Node_distribution.png → doc/htmldoc/img/Node_distribution.png b/doc/userdoc/img/Node_distribution.png → doc/htmldoc/img/Node_distribution.png
diff --git a/doc/userdoc/img/Node_distribution.svg → doc/htmldoc/img/Node_distribution.svg b/doc/userdoc/img/Node_distribution.svg → doc/htmldoc/img/Node_distribution.svg
diff --git a/doc/userdoc/img/One_to_one.png → doc/htmldoc/img/One_to_one.png b/doc/userdoc/img/One_to_one.png → doc/htmldoc/img/One_to_one.png
diff --git a/doc/userdoc/img/Process_vp_thread.png → doc/htmldoc/img/Process_vp_thread.png b/doc/userdoc/img/Process_vp_thread.png → doc/htmldoc/img/Process_vp_thread.png
diff --git a/doc/userdoc/img/Process_vp_thread.svg → doc/htmldoc/img/Process_vp_thread.svg b/doc/userdoc/img/Process_vp_thread.svg → doc/htmldoc/img/Process_vp_thread.svg
diff --git a/doc/userdoc/img/Receptor_types.png → doc/htmldoc/img/Receptor_types.png b/doc/userdoc/img/Receptor_types.png → doc/htmldoc/img/Receptor_types.png
diff --git a/doc/userdoc/img/free.png → doc/htmldoc/img/free.png b/doc/userdoc/img/free.png → doc/htmldoc/img/free.png
diff --git a/doc/userdoc/img/grid.png → doc/htmldoc/img/grid.png b/doc/userdoc/img/grid.png → doc/htmldoc/img/grid.png
diff --git a/...erdoc/img/nest_sionlib_file_format_v2.png → ...mldoc/img/nest_sionlib_file_format_v2.png b/...erdoc/img/nest_sionlib_file_format_v2.png → ...mldoc/img/nest_sionlib_file_format_v2.png
diff --git a/...erdoc/img/nest_sionlib_file_format_v2.svg → ...mldoc/img/nest_sionlib_file_format_v2.svg b/...erdoc/img/nest_sionlib_file_format_v2.svg → ...mldoc/img/nest_sionlib_file_format_v2.svg
diff --git a/doc/userdoc/img/precise1-300x175.png → doc/htmldoc/img/precise1-300x175.png b/doc/userdoc/img/precise1-300x175.png → doc/htmldoc/img/precise1-300x175.png
diff --git a/doc/userdoc/img/precise2-300x171.png → doc/htmldoc/img/precise2-300x171.png b/doc/userdoc/img/precise2-300x171.png → doc/htmldoc/img/precise2-300x171.png
diff --git a/doc/userdoc/img/python_interface.png → doc/htmldoc/img/python_interface.png b/doc/userdoc/img/python_interface.png → doc/htmldoc/img/python_interface.png
diff --git a/doc/userdoc/img/sample1_circgauss.png → doc/htmldoc/img/sample1_circgauss.png b/doc/userdoc/img/sample1_circgauss.png → doc/htmldoc/img/sample1_circgauss.png
diff --git a/doc/userdoc/img/sample2_rectanchor.png → doc/htmldoc/img/sample2_rectanchor.png b/doc/userdoc/img/sample2_rectanchor.png → doc/htmldoc/img/sample2_rectanchor.png
diff --git a/doc/userdoc/img/sample3_doughnutlinear.png → doc/htmldoc/img/sample3_doughnutlinear.png b/doc/userdoc/img/sample3_doughnutlinear.png → doc/htmldoc/img/sample3_doughnutlinear.png
diff --git a/doc/userdoc/img/sample4_gaussweights.png → doc/htmldoc/img/sample4_gaussweights.png b/doc/userdoc/img/sample4_gaussweights.png → doc/htmldoc/img/sample4_gaussweights.png
diff --git a/doc/userdoc/img/simulation_loop-241x300.png → doc/htmldoc/img/simulation_loop-241x300.png b/doc/userdoc/img/simulation_loop-241x300.png → doc/htmldoc/img/simulation_loop-241x300.png
diff --git a/doc/userdoc/img/spikes_one_neuron.pdf.png → doc/htmldoc/img/spikes_one_neuron.pdf.png b/doc/userdoc/img/spikes_one_neuron.pdf.png → doc/htmldoc/img/spikes_one_neuron.pdf.png
diff --git a/...erdoc/img/spikes_one_neuron_noise.pdf.png → ...mldoc/img/spikes_one_neuron_noise.pdf.png b/...erdoc/img/spikes_one_neuron_noise.pdf.png → ...mldoc/img/spikes_one_neuron_noise.pdf.png
diff --git a/doc/userdoc/img/time_definitions-300x61.png → doc/htmldoc/img/time_definitions-300x61.png b/doc/userdoc/img/time_definitions-300x61.png → doc/htmldoc/img/time_definitions-300x61.png
diff --git a/doc/userdoc/img/vm_one_neuron.pdf.png → doc/htmldoc/img/vm_one_neuron.pdf.png b/doc/userdoc/img/vm_one_neuron.pdf.png → doc/htmldoc/img/vm_one_neuron.pdf.png
diff --git a/doc/userdoc/img/vm_one_neuron_noise.pdf.png → doc/htmldoc/img/vm_one_neuron_noise.pdf.png b/doc/userdoc/img/vm_one_neuron_noise.pdf.png → doc/htmldoc/img/vm_one_neuron_noise.pdf.png
diff --git a/...erdoc/img/vm_psp_two_neurons.pdf-w400.png → ...mldoc/img/vm_psp_two_neurons.pdf-w400.png b/...erdoc/img/vm_psp_two_neurons.pdf-w400.png → ...mldoc/img/vm_psp_two_neurons.pdf-w400.png
diff --git a/doc/userdoc/img/vm_psp_two_neurons.pdf.png → doc/htmldoc/img/vm_psp_two_neurons.pdf.png b/doc/userdoc/img/vm_psp_two_neurons.pdf.png → doc/htmldoc/img/vm_psp_two_neurons.pdf.png
diff --git a/doc/userdoc/index.rst → doc/htmldoc/index.rst b/doc/userdoc/index.rst → doc/htmldoc/index.rst
diff --git a/doc/userdoc/installation/cmake_options.rst → doc/htmldoc/installation/cmake_options.rst b/doc/userdoc/installation/cmake_options.rst → doc/htmldoc/installation/cmake_options.rst
diff --git a/doc/userdoc/installation/conda_tips.rst → doc/htmldoc/installation/conda_tips.rst b/doc/userdoc/installation/conda_tips.rst → doc/htmldoc/installation/conda_tips.rst
diff --git a/doc/userdoc/installation/configuration.rst → doc/htmldoc/installation/configuration.rst b/doc/userdoc/installation/configuration.rst → doc/htmldoc/installation/configuration.rst
diff --git a/doc/userdoc/installation/hpc_install.rst → doc/htmldoc/installation/hpc_install.rst b/doc/userdoc/installation/hpc_install.rst → doc/htmldoc/installation/hpc_install.rst
diff --git a/doc/userdoc/installation/index.rst → doc/htmldoc/installation/index.rst b/doc/userdoc/installation/index.rst → doc/htmldoc/installation/index.rst
diff --git a/doc/userdoc/installation/linux_install.rst → doc/htmldoc/installation/linux_install.rst b/doc/userdoc/installation/linux_install.rst → doc/htmldoc/installation/linux_install.rst
diff --git a/doc/userdoc/installation/livemedia.rst → doc/htmldoc/installation/livemedia.rst b/doc/userdoc/installation/livemedia.rst → doc/htmldoc/installation/livemedia.rst
diff --git a/doc/userdoc/installation/mac_install.rst → doc/htmldoc/installation/mac_install.rst b/doc/userdoc/installation/mac_install.rst → doc/htmldoc/installation/mac_install.rst
diff --git a/...erdoc/installation/pynest_readme_link.rst → ...mldoc/installation/pynest_readme_link.rst b/...erdoc/installation/pynest_readme_link.rst → ...mldoc/installation/pynest_readme_link.rst
diff --git a/doc/userdoc/license.rst → doc/htmldoc/license.rst b/doc/userdoc/license.rst → doc/htmldoc/license.rst
diff --git a/doc/userdoc/mock_kernel.py → doc/htmldoc/mock_kernel.py b/doc/userdoc/mock_kernel.py → doc/htmldoc/mock_kernel.py
diff --git a/doc/htmldoc/models/models-main.rst b/doc/htmldoc/models/models-main.rst
@@ -0,0 +1,12 @@
+Models in NEST
+==============
+
+
+NEST provides a ton of models! Textbook standards like integrate-and-fire and Hodgkin-Huxley type models are available
+alongside high quality implementations of models published by the neuroscience community.
+
+* Discover :doc:`all the models in our directory <index>`
+
+Need to create your own?
+
+* Check out :doc:`NESTML <nestml:index>`, a domain-specific language supporting neuron and synapse models with a code generation backend that generates model code in C++ for NEST.
diff --git a/doc/userdoc/models/models-toc.rst → doc/htmldoc/models/models-toc.rst b/doc/userdoc/models/models-toc.rst → doc/htmldoc/models/models-toc.rst
diff --git a/doc/userdoc/guides/built-in_timers.rst → ...htmldoc/nest_behavior/built-in_timers.rst b/doc/userdoc/guides/built-in_timers.rst → ...htmldoc/nest_behavior/built-in_timers.rst
diff --git a/doc/htmldoc/nest_behavior/index.rst b/doc/htmldoc/nest_behavior/index.rst
@@ -0,0 +1,13 @@
+.. _behavior_index:
+
+How NEST works
+==============
+
+
+.. toctree::
+
+   built-in_timers
+   random_numbers
+   running_simulations
+   nest_server
+   using_nest_with_music
diff --git a/doc/userdoc/guides/random_numbers.rst → doc/htmldoc/nest_behavior/random_numbers.rst b/doc/userdoc/guides/random_numbers.rst → doc/htmldoc/nest_behavior/random_numbers.rst
diff --git a/doc/userdoc/guides/running_simulations.rst → ...doc/nest_behavior/running_simulations.rst b/doc/userdoc/guides/running_simulations.rst → ...doc/nest_behavior/running_simulations.rst
@@ -1,7 +1,7 @@
 .. _run_simulations:
 
-How to run simulations
-======================
+Simulation behavior
+===================
 
 Time-driven and event-driven approaches
 ---------------------------------------