DOC: Refresh code-website

[asoplata]

Firstly, when I say the "Code-website", specifically I mean https://jonescompneurolab.github.io/hnn-core/stable/index.html . I say this to differentiate it from the "Main HNN website" here https://hnn.brown.edu/ or the "New Tutorial" website.

This is intended as a catch-all issue to track all the TODOs that Austin needs to do in order to get the website "up to date". This does not include major architectural changes like the build system, but rather dealing with smaller things that have broken over time, improving the ease of contributing to documentation by changing most of the website to use Markdown (MyST), and small text improvements. This will be done through many smaller PRs.

Technical changes:

Note: I have done preliminary testing (unpushed) of all of the below, and everything works.

• Fix bugs in the sphinx Makefile
• Change the theme in order to fix the drop-downs ( menubar of website does not work on mobile #908 ) and search ( DOC: Search does not work on Sphinx-built documentation website #941 ):
  • See my comment here: menubar of website does not work on mobile #908 (comment) . Unfortunately, the easiest (and best) solution is switching our Sphinx theme. Since many things in doc/conf.py are theme-specific, I'm experimenting with how to get the page to use the new theme to resemble the older one.
  • The obvious theme to switch TO is https://pydata-sphinx-theme.readthedocs.io/en/stable/ . This will look familiar if you've spent time in the numerical computing community of Python, since it's used for the documentation of MNE, Numpy, Scipy, Pandas, etc. Importantly, this theme has built-in version switching https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/version-dropdown . In my tests with applying this theme, it fixes both of the above issues.
• Transition from ReStructured Text (RST) to Markdown (where applicable), specifically via the MyST-parser ( https://www.sphinx-doc.org/en/master/usage/markdown.html#markdown ):
  • Reasons: Markdown is significantly more popular and easier to use than RST, in part because it is far less powerful. Changing our main code-website documents to also support using Markdown via MyST https://myst-parser.readthedocs.io/en/latest/ allows us to continue using RST for some files, MyST syntax that maps to RST, and raw RST inside MyST files, but also users who only know Markdown to contribute more easily. Most of our non-API documentation on the code-website already makes very little use of RST, and most of them need very little work to convert to MyST (I've already done almost all the conversion, but haven't pushed them yet).
    • Part of why I think this is important is that I believe the vast majority of our newer developers/users may be familiar with Markdown, but are much less likely to be familiar with RST. One should not have to learn RST to contribute to our documentation, but I think if you are contributing on Github, there's a good chance you have already learned Markdown, and can contribute without having to learn what a directive really is, etc.
  • The major parts of the code-website which should not be converted to MyST due to difficulty are:
    • api.rst, which is the main file used to aggregate and reference the autodoc'd code doctrees
    • anything in generated or auto_examples, which are computer-generated anyways.

Webpage "authoring" work to do:

• README:
  • Add link to survey
• Install:
  • Install should become its own page.
    • ALL mention of pip install hnn_core[<extras>] with any "extra" dependencies should ALWAYS be shown in quotes. This will work across bash and zsh.
  • We should consider moving the installation part of the Parallel page to Installation.
  • There are many issues with the installation instructions for MPI that need to be fixed, including that we do not support it on Windows. I have documented most of the issues here https://www.notion.so/jonescompneurolab/s-notes-investigating-HNN-MPI-installation-on-Linux-Mac-circa-2024-b1ca56187e8641f78c7faa283b7a1cd7 . If people want, I can copy those notes here.
  • Add Troubleshooting section to Install
    • Test, and add documentation of how to rebuild mechanisms if they fail to build during install
  • Once the New Tutorial website is up, provide a link to it at the bottom of the Install page
• Like many popular packages do, we should separate "Usage" instructions to their own page, separate from "Installation", partly because Installation is much more complex. The "Usage" page should be severely restricted and link to the new Tutorials website.
• Contributing page:
  • Add mention of the Code of Conduct to the Contributing page
  • Add description of Ruff linting usage a la make test to Contributing
  • Add "tips and tricks" such as pytest --pdb
  • Move the "how to make a release" on the wiki to a sub-page of Contributing, and polish it
• What's new:
  • Do DOCS: Review all contributions before v0.4 release #919
  • Add commented instructions to the top of what's new, and reference them
  • Add comment with guide to how to add
• API:
  • Review actual API to see if any interfaces need to be added or removed