Merge remote-tracking branch 'nest/master' into connection_semantics_…

…prototype_merge

.github/workflows/build_dispatch.yml

@@ -0,0 +1,14 @@
+on: [push]
+
+jobs:
+  trigger_externals:
+    name: "Trigger downstream repos"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger nest/nest-extension-module CI
+        uses: peter-evans/repository-dispatch@v2
+        with:
+          token: ${{ secrets.NEST_EXTENSION_MODULE_TRIGGER_TOKEN }}
+          repository: 'nest/nest-extension-module'
+          event-type: dispatch-event_nest-update
+          client-payload: '{"ref": "${{ github.ref }}", "sha": "${{ github.sha }}"}'

.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

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/).

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

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.

doc/userdoc/citing-nest.rst → doc/htmldoc/citing-nest.rst

@@ -1,11 +1,9 @@
-:orphan:
-
 .. _cite_nest:
 
 Cite NEST
 =========
 
-Please cite the version of NEST you used in your work. You can :ref:`let us know <community>` about your publications that used NEST, and we
+Please cite the version of NEST you used in your work. You can :ref:`let us know <contact_us>` about your publications that used NEST, and we
 will add them to our `publication list <https://www.nest-simulator.org/publications/>`_; this will help make them
 visible to potential readers.
 

doc/userdoc/community.rst → doc/htmldoc/community.rst

@@ -1,10 +1,15 @@
 .. _community:
 
-NEST Community
-==============
+Community
+=========
+
+.. _contact_us:
+
+Contact us
+----------
 
 Mailing list
-------------
+~~~~~~~~~~~~
 
 The NEST users mailing list is intended to be a forum for questions on the usage
 of NEST, the exchange of code and general discussions about NEST.  The philosophy
@@ -16,29 +21,35 @@ 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
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
 Every two weeks, we have an open video conference to discuss current issues and developments in NEST.
 We welcome users with questions regarding their implementations or issues they want help solving to join.
 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.
+.. include:: getting_help.rst
 
-If you have used NEST in your research, let us know!
-Don't forget to :ref:`cite NEST <cite_nest>` in your work.
+Explore the NEST ecosystem
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Have a talk or poster where you used NEST? `Download our logo  <https://github.com/nest/nest-simulator/tree/master/doc/logos>`_!
+.. toctree::
+  :maxdepth: 1
 
-Become a NEST member
---------------------
+  News and updates <https://nest-simulator.org>
+  Publications <https://www.nest-simulator.org/publications/>
+  NEST Initiative <https://www.nest-initiative.org/>
+  related_projects
+  citing-nest
 
-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>`_.
 

doc/userdoc/conf.py → doc/htmldoc/conf.py

@@ -44,14 +44,14 @@
 
 
 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"))
 
 source_suffix = '.rst'
-master_doc = 'contents'
+master_doc = 'index'
 
 # Create the mockfile for extracting the PyNEST
 
@@ -164,7 +164,8 @@
 html_theme = 'sphinx_rtd_theme'
 html_logo = str(doc_build_dir / 'static/img/nest_logo.png')
 html_theme_options = {'logo_only': True,
-                      'display_version': True}
+                      'display_version': True,
+                      'style_external_links': True}
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

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

doc/userdoc/guides/using_nest_with_music.rst → doc/htmldoc/connect_nest/using_nest_with_music.rst

@@ -245,7 +245,7 @@ which yields the following output:
 
 ::
 
-	Nov 23 11:18:23 music_message_in_proxy::calibrate() [Info]:
+	Nov 23 11:18:23 music_message_in_proxy::pre_run_hook() [Info]:
 		Mapping MUSIC input port 'msgdata' with width=0 and acceptable latency=0
 		ms.
 
@@ -350,7 +350,7 @@ which yields the following output:
 
 ::
 
-	Nov 23 11:33:26 music_cont_in_proxy::calibrate() [Info]:
+	Nov 23 11:33:26 music_cont_in_proxy::pre_run_hook() [Info]:
 		Mapping MUSIC input port 'contdata' with width=10.
 
 	Nov 23 11:33:26 NodeManager::prepare_nodes [Info]:

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
 --------------------------------
 
@@ -70,4 +72,9 @@ See also https://github.com/nest/nest-extension-module for details about the gen
 Have a question?
 ----------------
 
-If you want to get in contact with us, see our :ref:`community` page for ways you can reach us.
+If you want to get in contact with us, see our :ref:`contact_us` section for ways you can reach us.
+
+.. note::
+
+   For all developer related topics see our :ref:`developer_space`
+

doc/htmldoc/developer_space/guidelines/code_review_guidelines.rst

@@ -0,0 +1,49 @@
+.. _code_guidelines:
+
+Code review guidelines
+======================
+
+Using our purely :ref:`pull-request-based workflow <git_workflow>`,
+code can be developed very flexibly by internal and external
+contributors. At the same time this workflow allows us to enforce
+stricter rules on code that ends up in the public repository.
+
+Following are rough guidelines for the code reviewers. These are not
+meant to prevent progress, but to keep up the code quality as the
+number of developers is growing. All of this is not set in stone and
+can be discussed on the :ref:`NEST mailing lists <contact_us>`.
+
+* In most cases, each pull request needs an OK from the
+  CI platform and at least two reviewers to be merged.
+* The two reviews have to cover the technical side (i.e., if the code
+  does the right thing and is architecturally sound) and the content
+  side (i.e., if the code is scientifically correct and fixes an
+  actual issue).
+* For changes labeled “not code” or “minor” (e.g., changes in
+  documentation, fixes for typos, etc.), the need for a second code
+  review can be waived, and a single review plus the OK from the CI
+  system is sufficient to merge the request.
+* New features like SLI or PyNEST functions, neuron or synapse models
+  need to be accompanied by one or more tests written in either SLI or
+  Python.
+* Each change to the code has to be reflected in the
+  corresponding examples and documentation.
+* A pull request should be coherent and contain only changes that
+  belong together.
+* Please also check that the typesetting of the documentation looks
+  correct. To learn how to test the documentation locally offline,
+  please check out our :ref:`User documentation workflow
+  <userdoc_workflow>`.
+
+
+Before merging, reviewers have to make sure that:
+
+1. pull request titles match the actual content of the PR and
+   be adequate for the release notes
+1. pull request titles are complete sentences that start with an
+  upper-case, present-tense verb and end without punctuation
+1. pull requests are assigned to projects and properly and completely
+   labeled
+1. all discussions are settled and all conversations are marked as
+   resolved
+1. there are no blocking issues mentioned in the comments

doc/userdoc/contribute/styleguide/sample_doc.rst → doc/htmldoc/developer_space/guidelines/styleguide/sample_doc.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 .. _sample_doc:
 
 Main title of document

doc/userdoc/contribute/styleguide/styleguide.rst → doc/htmldoc/developer_space/guidelines/styleguide/styleguide.rst

@@ -72,7 +72,7 @@ references should be provided for clarity in introductory texts and the :ref:`gl
 
 If you have further questions about style rules not addressed here, use
 `the Microsoft style guide <https://docs.microsoft.com/en-us/style-guide/welcome/>`_ as a resource
-or ask on the :ref:`mailing list <community>`.
+or ask on the :ref:`mailing list <contact_us>`.
 
 How to phrase content in NEST
 -----------------------------

doc/htmldoc/developer_space/index.rst

@@ -0,0 +1,47 @@
+.. _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.
+
+
+.. 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
+

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
+