Update documentation index page and navigation structure #2969

jessica-mitchell · 2023-10-05T11:25:09Z

This PR improves the overall landing page and structure of contents.

Resolves #2783

The new index page

It removes the index.html template in favour of a restructured text page, which will eliminate issues with compatibility between the sphinx_material theme and custom template.
contains a 'carousel' where we can highlight new and interesting examples. (TODO, decide on which examples to showcase)
contains a modified table of contents (TOC): details below
contains a conceptual diagram using elements from NEST Desktop and images courtesy of A. Fischer TODO: Add description to diagram
A 'get started here' button leads to the new tutorials and guides section, which is what is seen on the TOC

The new tutorials and guides section

As discussed with @clinssen, as well as others, we decided to encapsulate all document material together in one place. Previously the tutorial for PyNEST and MUSIC were separated from other document guides.

I chose to use heading Tutorials and Guides, because not all the documents we have can be defined as tutorials in my opinion.

The tutorials and guides are structured in cards similar to before, but now the first row is organized by topics that should help users get started:

the first card simply is the first steps - getting to know NEST - here the installation instructions are repeated, the PyNEST tutorial is added, along with the one neuron example, for those who want a quicker overview, and the video tutorial for those who prefer that medium
The second card deals with the actual creation of the script that the user needs, and what guides would be helpful for this. In this regard I was thinking of the basic things you do with NEST (create, connect, simulate, record) note: stimulate is not included for brevity and we don't have that extensive amount of docs on it. In this context, I am making the assumption here that users would need to look into models, connection management, simulation behavior and recorders for getting data out for analysis.
The third card deals more with the code aspects of the script, that is, the functionality allowed by Nodecollections, parameter objects. This would help users optimize their script and show them ways of manipulating the data for their desired outcomes.

After this first row, comes Additional topics
Here I try to organize them as they were before, with a bit more text is added to help clarify the links.

Changes in the Networks card

Added to the spatially_structured_networks is the network models (mam and microcircuit). Not sure if this is the best choice.

The main table of contents

Now the table of contents is divided into 3 sections "usage", "community" and "related projects"

Usage contains the basic topics for docs - install, tutorials and guides, examples, API, models, glossary and then model implementations (which could be removed if it doesnt belong on top level), and technical docs (renamed from developer docs to move away from user vs developer)
Community contains topics related to contributing to NEST, citing NEST, contact, what's new in NEST and also link to the homepage (we could also add publications and events as links within the homepage?). Basically all the things that involve the user community
Related projects contain the other NEST projects - we discussed adding a diagram for other projects and explain the ecosystem that NEST is in, but that is for another PR

Other changes

A modified colour theme is used (removing the green in favour of sticking to orange-brown and light and dark blue)
A cleanup of the static folder, and included jquery into template layout.html which solved a bug in the search.
The contribute section is split from the old developer docs in an attempt to make contribution section more available for everyone

clinssen · 2023-10-05T12:03:13Z

Thanks for the great work!

Just some early observatations:

I would not make "model implementations" a top-level category, at it just contains some scattered notes about a few models. Instead, make sure these notebooks are linked from the models to which they apply. For instance, link the Hill & Tononi notebook from the Hill & Tononi neuron and synapse model documentation pages.

I would move away from the "conceptual approach" imagemap as it's hard to navigate and the interface is a bit yesteryear. Instead, just expand all of the categories that can be clicked on the image into tiles (stimulation devices, neurons, synapses, connections, and recording devices).

What is the difference between "technical documentation" and "contribute to NEST"? Suggest to merge and use only the latter heading.

jessica-mitchell · 2023-10-05T12:11:29Z

Thanks for the great work!

Just some early observatations:

I would not make "model implementations" a top-level category, at it just contains some scattered notes about a few models. Instead, make sure these notebooks are linked from the models to which they apply. For instance, link the Hill & Tononi notebook from the Hill & Tononi neuron and synapse model documentation pages.

Yah, ok they should be linked from respective models, just wanted to check

I would move away from the "conceptual approach" imagemap as it's hard to navigate and the interface is a bit yesteryear. Instead, just expand all of the categories that can be clicked on the image into tiles (stimulation devices, neurons, synapses, connections, and recording devices).

I see your point; @jougs do you have thoughts on this, since this is an idea we discussed? The goal here was to provide a visual representation of how a network comes together.

What is the difference between "technical documentation" and "contribute to NEST"? Suggest to merge and use only the latter heading.

Right now, you're right there isnt much difference, but I am hoping we get some more technical docs that lean more on the C++ side.

…ulator into new-index-page

clinssen

Super cool and a huge improvement, much obliged!

clinssen · 2023-10-30T10:30:11Z

doc/htmldoc/contribute.rst

+    .. 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>`_


Suggested change

an issue on GitHub using `the templates <https://github.com/nest/nest-simulator/issues/new/choose>`_

an issue on GitHub using `the templates <https://github.com/nest/nest-simulator/issues/new/choose>`_.

clinssen · 2023-10-30T10:31:01Z

doc/htmldoc/contribute.rst

+
+   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*.


suggest to turn this into a link, writing @ as [at] probably isn't going to stop any spambots and it's a bit of an inconvenience

Suggested change

form to transfer your copyright to the NEST initiative and send it to *info [at] nest-initiative.org*.

form to transfer your copyright to the NEST initiative and send it to *info@nest-initiative.org*.

clinssen · 2023-10-30T11:21:10Z

doc/htmldoc/developer_space/index.rst


-    .. grid-item-card::  Continuous integration
+       * Here you can find details on our :ref:`CI workflow <cont_integration>`



The "SLI documentation" button just below here is devoid of text. Could we add a little one-liner? "SLI is the internal scripting language of NEST. It is now deprecated and not recommended for new applications". Perhaps also on the sli_docs index page as well.

clinssen · 2023-10-30T11:21:38Z

...tmldoc/developer_space/workflows/documentation_workflow/developer_documentation_workflow.rst

@@ -1,10 +1,10 @@
 .. _devdoc_workflow:

-Developer documentation workflow
-################################
+Techincal documentation workflow


Suggested change

Techincal documentation workflow

Technical documentation workflow

clinssen · 2023-10-30T11:23:10Z

doc/htmldoc/devices/index.rst

@@ -1,10 +1,29 @@
 .. _device_index:

-All about devices in NEST
-=========================
+All about recording and stimulating networks in NEST


Please add a link to this document under "More about devices" on get-started_index.html — or alternatively, delete devices/index.rst page as it contains very little content; just merge the links in to the "More about devices" box on get-started_index.html.

clinssen · 2023-10-30T11:31:42Z

doc/htmldoc/index.rst

+    NEST is used in computational neuroscience to model and study behavior of large networks of neurons.
+
+    The models describe single neuron and synapse behavior and their connections.
+    Different mechanisms of plasticity can be used to investigate artificial learning


Suggested change

Different mechanisms of plasticity can be used to investigate artificial learning

Different models of plasticity can be used to investigate the mechanisms learning

possibly, this is a "standard text" paragraph and edits should go in somewhere upstream instead?

clinssen · 2023-10-30T11:32:30Z

doc/htmldoc/index.rst

+
+----
+
+Conceptual approach


I would vote to remove this paragraph and the imagemap figure.

clinssen · 2023-10-30T11:39:00Z

doc/htmldoc/static/img/arrow_left.svg

there seems to be a glitch in this figure on the top

clinssen · 2023-10-30T11:39:16Z

doc/htmldoc/static/img/device_text.svg

issue with transparency

clinssen · 2023-10-30T11:39:50Z

doc/htmldoc/static/img/synapse_text.svg

Just to double-check that Angela is credited as original creator of the images.

jessica-mitchell · 2024-01-17T11:09:56Z

@clinssen I am closing this PR in lieu of splitting it up into multiple PRs for a cleaner and easier review process. Thanks for your contributions thus far.

jessica-mitchell added 30 commits August 30, 2023 14:30

setup new index

f42a109

fix up conf, modify css style

bb97a6f

add brain network image, add dropdowns

ff1494c

add popup css js

8da8990

add logos white and black

581fd33

update toc

4c18df5

fix up sidebar and svg

7698962

change toc structure, remove dropdowns

31edd53

move all guides and tutorials under one page

c89f088

split contribute section to separte page, reorganize developer index

0791691

add toc page for model details

66887d5

add icons

17b5c33

add pynest tut index

6fa2043

update css

f8874af

Merge branch 'master' into new-index-page

528650c

remove script from index

23777c8

fix link

cf03e9c

modify guides index page, add toc for ssn

6c9270e

Merge branch 'master' into new-index-page

defa303

update developer space

9925e07

modify index and getting started pages

c78adc8

add arows and new icon

b7faf63

add css button, arrows

eae7d5c

minor adjusts, change to technical docs

f379d74

modify index page

7aeb7be

rm extra js

25ab53b

add toc

c8a2fc6

add jquery to template

07f91da

remove page

8dc52f2

remove and update images css

f153794

jessica-mitchell added the S: Normal Handle this with default priority label Oct 5, 2023

jessica-mitchell mentioned this pull request Oct 5, 2023

Change tutorials and examples organisation #2866

Closed

Merge branch 'master' into new-index-page

0db3f32

clinssen self-requested a review October 5, 2023 12:03

jessica-mitchell added 8 commits October 5, 2023 18:02

remove implementations

730e293

Merge branch 'master' into new-index-page

8cbba4d

Merge branch 'new-index-page' of github.com:jessica-mitchell/nest-sim…

8e5af1d

…ulator into new-index-page

try various hover mechanisms

fafaa58

get hoverxref working

941c3ce

modify install pages

0c90e54

update nest desktop /ml and icon

82e120c

modify links in get started, css

012b127

clinssen reviewed Oct 30, 2023

View reviewed changes

jessica-mitchell added 10 commits November 14, 2023 13:17

Merge branch 'master' into new-index-page

f9876b4

add svgs

8fd949f

modify mermaid, css

981f073

rm size hoverxref

9d170f2

add svgs

1a54681

add plantuml diagram

ce07bfc

Merge branch 'master' into new-index-page

573e427

add windows options

7db39b7

remove hover

1f7dc7d

update diagram and links

b811a83

jessica-mitchell mentioned this pull request Jan 17, 2024

Modify doc index page #3066

Merged

jessica-mitchell closed this Jan 17, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update documentation index page and navigation structure #2969

Update documentation index page and navigation structure #2969

jessica-mitchell commented Oct 5, 2023 •

edited

Loading

clinssen commented Oct 5, 2023

jessica-mitchell commented Oct 5, 2023

clinssen left a comment

clinssen Oct 30, 2023

clinssen Oct 30, 2023

clinssen Oct 30, 2023

clinssen Oct 30, 2023

clinssen Oct 30, 2023

clinssen Oct 30, 2023

clinssen Oct 30, 2023

clinssen Oct 30, 2023

clinssen Oct 30, 2023

clinssen Oct 30, 2023

jessica-mitchell commented Jan 17, 2024

	an issue on GitHub using `the templates <https://github.com/nest/nest-simulator/issues/new/choose>`_
	an issue on GitHub using `the templates <https://github.com/nest/nest-simulator/issues/new/choose>`_.

	form to transfer your copyright to the NEST initiative and send it to info [at] nest-initiative.org.
	form to transfer your copyright to the NEST initiative and send it to info@nest-initiative.org.


		.. grid-item-card:: Continuous integration
		* Here you can find details on our :ref:`CI workflow <cont_integration>`

	Techincal documentation workflow
	Technical documentation workflow

	Different mechanisms of plasticity can be used to investigate artificial learning
	Different models of plasticity can be used to investigate the mechanisms learning


		----

		Conceptual approach

Update documentation index page and navigation structure #2969

Update documentation index page and navigation structure #2969

Conversation

jessica-mitchell commented Oct 5, 2023 • edited Loading

The new index page

The new tutorials and guides section

Changes in the Networks card

The main table of contents

Other changes

clinssen commented Oct 5, 2023

jessica-mitchell commented Oct 5, 2023

clinssen left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jessica-mitchell commented Jan 17, 2024

jessica-mitchell commented Oct 5, 2023 •

edited

Loading