Restructure the userdoc directory

[jessica-mitchell]

This PR reorganizes the documentation to improve findability of different topics, both in the source on GitHub and on Read the docs.

In the userdoc/ directory the guides/ have been removed in favour of more descriptive folders
New folders:

• neuron_docs/ -- docs about neurons
• synapse_docs/ -- docs about synapses and connections
• device_docs/ -- docs about devices
• coupling_nest_docs/ -- docs about other tools that connect with nest
• nest_behavior_docs/ -- docs about how nest works
• hpc_docs/ -- docs about hpc setup

A new table of contents was also created for highlighting topics on Read the Docs:
You can see the structure output here: https://nest-test.readthedocs.io/en/new-doc-folder-structure/contents.html

In addition, I moved the developer docs back into userdoc/ because

1. I want to build the dev docs with Sphinx and that's done easiest if it's in userdoc/
2. I want to include all docs that relate to maintaining, contributing or developing the documentation or code in anyway in devdoc/. (Thus all contribution guidelines, styleguides, workflows, go in here)
3. Note that the actual doxygen output is not rendered on Rtd yet

See the output table of contents for the developer area here: https://nest-test.readthedocs.io/en/new-doc-folder-structure/devdoc/index.html

Please comment if you have suggestions for alternatives!

[clinssen]

• In general, I'm not super enthusiastic about making subdirectories userdoc and devdoc, because these "deep" hierarchies never work in practice. Now this PR has doc/userdoc/devdoc, which is particularly confusing. I would suggest to put everything just right under doc in the root of the repository.

• A new table of contents was also created for highlighting topics on Read the Docs

  This is just to illustrate the new menu structure, right? The items are one-to-one the same as on the left-hand column menu. I'd recommend against including the page itself (a site should not need a "sitemap").

• Do we need the _docs suffixes on all subdirectories?

[jessica-mitchell]

• In general, I'm not super enthusiastic about making subdirectories userdoc and devdoc, because these "deep" hierarchies never work in practice. Now this PR has doc/userdoc/devdoc, which is particularly confusing. I would suggest to put everything just right under doc in the root of the repository.

Yes, I agree to some extent - I would not want devdoc under userdoc; this was just a way to get the docs to build with the current hierarchy.
I do think we can separate developer docs from user docs - in the sense that I mentioned above: any documentation that is used to modify and develop code or documentation, all workflows (for contributing, git etc) and templates should be under 'developer'.
We could also remove devdoc / userdoc completely and create subdirectories for each topic. But I like the idea of grouping all docs that a developer may need together, as is here https://nest-test.readthedocs.io/en/new-doc-folder-structure/devdoc/index.html.
But this could be done via linking to different folders in the repo.

* > A new table of contents was also created for highlighting topics on Read the Docs
  
  
  This is just to illustrate the new menu structure, right? The items are one-to-one the same as on the left-hand column menu. I'd recommend against including the page itself (a site should not need a "sitemap").

Yes, I showed the toc page to highlight the structure. But this page is available on Read the docs (currently if you click the nest logo I think you get contents.html, automatically). It is what the sidebar will show on every page, including the new theme.

* Do we need the `_docs` suffixes on all subdirectories?

Probably not - I am up for removing it, and any alternative naming suggestions.

[jessica-mitchell]

@pnbabu @clinssen I think I have addressed all you comments thus far. Just a kind reminder to finish the review when you can, thanks!

[pnbabu]

@jessica-mitchell The CI is failing for something unrelated to the changes in this PR. Otherwise, this looks good to me.

[clinssen]

Inspired by https://documentation-for-annarchy.readthedocs.io/, can we have a menu that only has the items:

• Home: subsumes current "Cite NEST" and "License". Add a link to "NEST Initiative" on the front page with a logo; external link should not be in the menu structure. Same for "Publications". Also subsume "Related Projects". All of these can just be rendered as different headers on a single landing page. Front page could include the video tutorial.
• Installation: current "Install NEST"
• Manual: covers NEST internals, current "Understand how NEST works", "Glossary", "From NEST 2.x to 3.x", "Model directory", MUSIC interface
• Examples: subsumes current PyNEST part of "Tutorials" and "PyNEST example scripts"
• API: current "PyNEST API", hopefully in the future this will also include the C++ API
• Contributing to NEST: subsumes current "Developer space"
• Getting help: subsumes current "Contact us" and "Get help"

By "subsume", I mean these pages go under this part of the hierarchy.

All of these top-level menu items would be collapsed by default, giving some space rather than the overwhelming number of items there are now.

[jessica-mitchell]

Inspired by https://documentation-for-annarchy.readthedocs.io/, can we have a menu that only has the items:

I see they are using the material theme, which is what we'll be moving towards.

I understand there are a lot of topics on the toc, but I am a little weary of hiding topics too.

* **Home**: subsumes current "Cite NEST" and "License". Add a link to "NEST Initiative" on the front page with a logo; external link should not be in the menu structure. Same for "Publications". Also subsume "Related Projects". All of these can just be rendered as different headers on a single landing page. Front page could include the video tutorial.

I do agree though that many of these links can be subsumed. However, due to the lack of proper citations we have encountered I think "cite NEST" should be very visible. (How this should be handled exactly I am not sure)
Reminder that there are major changes that will happen to the docs theme in the (hopefully) upcoming weeks, so I don't want to make changes to the front page.

* **Installation**: current "Install NEST"

* **Manual**: covers NEST internals, current "Understand how NEST works", "Glossary", "From NEST 2.x to 3.x", "Model directory", MUSIC interface

I am not really in favour of the word "manual", my first thought when I read "manual" is some very dense, 5000 page instruction booklet. Directories like glossaries, in at least my head, fit very much into the reference material category.
Also, we used to have "guides" as a catch-all term. And the goal of creating all these more descriptive categories was so users/developers can discover and find topics more easily, rather than scrolling through a list of random assorted topics. On the other hand, showing all these topics as it is currently might also be overwhelming...

* **Examples**: subsumes current PyNEST part of "Tutorials" and "PyNEST example scripts"

I like tutorials as a separate category, or at least keeping the term visible.

* **API**: current "PyNEST API", hopefully in the future this will also include the C++ API

What do you mean by C++ API?

* **Contributing to NEST**: subsumes current "Developer space"

* **Getting help**: subsumes current "Contact us" and "Get help"

By "subsume", I mean these pages go under this part of the hierarchy.

All of these top-level menu items would be collapsed by default, giving some space rather than the overwhelming number of items there are now.

So I went ahead and played with the toc to fit with what you describe, and so I can get a feel for it and found its behaviour not as nice as the example you provided.

• The sidebar toc doesn't seem to be expandable without actually redirecting you to that page. The + / - icon is only visible after I expand the list for that item.
• The table of contents (contents.html) is (even with a set limited depth) displaying all levels of titles, which I think looks very overwhelming. (There are likely a few theme and toc options to play with to make this behave more nicely).
• I did like how easy it is to see get a really quick overview; it's certainly very readable

So after all that - I think you have a valid point, and we could probably condense this list, but I am not convinced that it makes sense to do it to such a degree, as is for annarchy, nor do I really want to fight with the sphinx-rtd-theme, if I have a PR waiting in the wings with the a new theme that would need to be configured differently.

My suggestion would be to have as headlines

• install NEST
• examples & tutorials
• understand nest works > what's there now
• reference material (or maybe directories) > glossary, model directory, release notes?
• PyNEST API (to differentiate from SLI, if necessary)
• Get help > help and contact
• Contribute > developer space
• Community > related projects, links to nest-simulator / initative

I would also suggest doing this in new theme

[clinssen]

Thanks for your kind response to my radical suggestions!

I see they are using the material theme, which is what we'll be moving towards.

Just focusing on the menu for now.

I am not really in favour of the word "manual"

Absolutely sympathize in having descriptive titles rather than words that are thinly veiled synonyms of "miscellaneous". "How NEST works" also good.

I like tutorials as a separate category, or at least keeping the term visible.

"Tutorials" instead of "Examples" would be also good.

What do you mean by C++ API?

The NEST C++ API as defined in https://github.com/nest/nest-simulator/blob/master/nestkernel/nest.h should eventually also be part of the API documentation.

* The sidebar toc doesn't seem to be expandable without actually redirecting you to that page. The  + / - icon is only visible after I expand the list for that item.

That seems alright if it's a page that helpfully lists the sub-items under there; otherwise I'd be happy to look into fixing this on a technical level; I don't think it'll be very difficult with Javascript.

* The table of contents (contents.html) is (even with a set limited depth) displaying all levels of titles, which I think looks very overwhelming. (There are likely a few theme and toc options to play with to make this behave more nicely).

contents.html is like a "sitemap" and should never be necessary to visit.

So after all that - I think you have a valid point, and we could probably condense this list, but I am not convinced that it makes sense to do it to such a degree, as is for annarchy, nor do I really want to fight with the sphinx-rtd-theme, if I have a PR waiting in the wings with the a new theme that would need to be configured differently.

Agree, let's look at the theme and Javascript together after this PR.

My suggestion would be to have as headlines

* install NEST

* examples & tutorials

* understand nest works > what's there now

* reference material  (or maybe directories) > glossary, model directory, release notes?

* PyNEST API  (to differentiate from SLI, if necessary)

* Get help  > help and contact

* Contribute  > developer space

* Community > related projects, links to nest-simulator / initative

100% on board with this!

"Reference material" could be interchangable with "How NEST works", whichever title you prefer.

In "PyNEST API", I feel like "PyNEST" is too much technical detail (it raises the question, what is this thing called PyNEST?) so I would suggest just going for "Python API" or "NEST API" (the latter slightly more compatible with the awaited C++ API additions).

[jessica-mitchell]

@clinssen I've simplified the main toc based on our discussion. I kept the model directory as a link, becasue I thought that might be something like the API users may want to explore. Please approve if you agree :) see: https://nest-test.readthedocs.io/en/new-doc-folder-structure/
Just something to note for future, I think there is more work to be done to make index pages more visually appealing, but I think the structure is vastly improved.

[jessica-mitchell]

@clinssen ping!

[clinssen]

This is shaping up really nicely! Just a few small points.

• Move "From NEST 2.x to 3.x" to the bottom of the list under "Understand how NEST works"
• "NEST models" page can probably be removed; links should be merged elsewhere where it makes sense
• "Troubleshooting" is not in any category, could go under "Get help"
• "Get help" and "Community" seems like they could be merged. I anyway expect nest.help() and nest.helpdesk() to disappear before long, which eliminates most of the content of the "Get help" page.
• "Community" page: first sections are links, later sections are text on the page; this is confusing.
• Can we add an icon in front of RtD-external links? See style_external_links option in the template.
• Clicking the top-left logo should link to the landing page, not ToC
• GNU License link on the front page is broken
• padding-left: 2rem seems excesive on unordered lists, especially the left-side menu column. Please make different styles for wy-menu ul and rst-content ul.

[jessica-mitchell]

* Move "From NEST 2.x to 3.x" to the bottom of the list under "Understand how NEST works"

moved lower down

* "NEST models" page can probably be removed; links should be merged elsewhere where it makes sense

changed link fo rnow to the directory ( I figured it doesnt hurt to have it twice, evenutally that models page should contain more info)

* "Troubleshooting" is not in any category, could go under "Get help"

It is actually in get help

* "Get help" and "Community" seems like they could be merged. I anyway expect nest.help() and nest.helpdesk() to disappear before long, which eliminates most of the content of the "Get help" page.

put get help in community, although I think it's less intuitive to find help this way - but still ok for me

* "Community" page: first sections are links, later sections are text on the page; this is confusing.

moved content around

* Can we add an icon in front of RtD-external links? See `style_external_links` option in the template.

yes, thanks for pointing this out, somehow I missed this option when looking at the config before

* Clicking the top-left logo should link to the landing page, not ToC

fixed

* GNU License link on the front page is broken

fixed

* `padding-left: 2rem` seems excesive on unordered lists, especially the left-side menu column. Please make different styles for `wy-menu ul` and `rst-content ul`.

I tried to change this, but failed in my initial attempts, and I dont want to spend a lot of time on css - as the new theme should take its place soon (and by next release if all goes to plan).

@clinssen I've addressed your comments, if satisfied please approve thanks!

[clinssen]

Many thanks! I'm approving already.

Minor things to fix:

• NEST Contributor Agreement link is broken on the Contribute page.
• FAQ seems to be missing in the menu (perhaps I overlooked it). Perhaps under Community/Get Help? Or should FAQ be removed altogether as it's a bit of a "miscellaneous" category?

Perhaps you could double-check the RtD documentation build log; I'm not sure but it might emit warnings there in case of broken links or orphaned documents.

[jessica-mitchell]

@clinssen thanks for approving I will take note of your last comments and apply them to a different PR