Update documentation site instructions

README.md

@@ -183,7 +183,7 @@ Our tests run on GitHub Actions on push and PR via `tox` ([tests.yml](https://gi
 
 [https://NeuroRuler.readthedocs.io](https://NeuroRuler.readthedocs.io)
 
-See [.readthedocs.yaml](https://github.com/NIRALUser/NeuroRuler/blob/main/.readthedocs.yaml) and [docs/](https://github.com/NIRALUser/NeuroRuler/tree/main/docs) to contribute.
+To contribute, see [docs/](https://github.com/NIRALUser/NeuroRuler/tree/main/docs). Build/setup instructions [here](https://neuroruler.readthedocs.io/en/latest/libraries.html#sphinx-setuptools). Note that it is possible to write site content in Markdown and inline RST in the Markdown file when needed - I just didn't find out until after this project was completed.
 
 [Team website](https://tarheels.live/comp523teamd/)
 

docs/conf.py

@@ -33,8 +33,7 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.autodoc",
     "sphinx_rtd_theme",
-    # For parsing Markdown
-    "m2r2",
+    "myst_parser",
 ]
 
 templates_path = ["_templates"]
@@ -49,8 +48,6 @@
 html_theme = "sphinx_rtd_theme"
 html_static_path = ["_static"]
 
-# Source: https://stackoverflow.com/questions/59215996/how-to-add-a-logo-to-my-readthedocs-logo-rendering-at-0px-wide
-html_static_path = ["_static"]
 html_favicon = "nr_logo.ico"
 html_logo = "_static/nr_logo.jpg"
 html_theme_options = {
@@ -59,7 +56,8 @@
 }
 
 
-# Prevents __init__ from being ignored
+# Prevents autodocumentation from ignoring __init__
+# Normally unneeded but we want autodocumentation to pick up Exception __init__ functions
 # Source: https://stackoverflow.com/questions/5599254/how-to-use-sphinxs-autodoc-to-document-a-classs-init-self-method
 def skip(app, what, name, obj, would_skip, options):
     if name == "__init__":

docs/index.rst

@@ -6,19 +6,13 @@
 .. role:: raw-html(raw)
     :format: html
 
-.. note::
-
-   Most of this page is the README from `GitHub <https://github.com/NIRALUser/NeuroRuler>`_.
-
-   For content unique to this site, see the sidebar :math:`\leftarrow`
-
 .. mdinclude:: ../README.md
 
 Contents
 ########
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    structure
    libraries

docs/libraries.rst

@@ -501,49 +501,53 @@ you should have already installed dependencies via pip.
 
 .. note:: :code:`docs/_build` is gitignored.
 
-You can open :code:`docs/_build/html/index.html` in a web browser #[macos_open_html]_ to check out the site before pushing, which
+You can open :code:`docs/_build/html/index.html` in a web browser [#macos_open_html]_ to check out the site before pushing, which
 will automatically update the
 website. From now on, you can just run :code:`make html` to update the html pages.
 
-However, you may need to run :code:`sphinx-apidoc -o . ../NeuroRuler` from the :code:`docs/` directory
+However, for autodocumentation of source code, you will need to run :code:`sphinx-apidoc -o . ../NeuroRuler` from the :code:`docs/` directory
 if a new package is created. Make sure :code:`__init__.py` files exist for any package you want
-to be discovered.
+to be discovered. See `this page <modules.html>`_ to view our auto-generated documentation of `source code <_modules/index.html>`_.
 
-You can edit `docs/index.rst <https://github.com/NIRALUser/NeuroRuler/blob/main/docs/index.rst>`_,
-which is the homepage, or `docs/libraries.rst <https://github.com/NIRALUser/NeuroRuler/blob/main/docs/libraries.rst>`_, which
-is this page. `Documentation <modules.html>`_ for `source code <_modules/index.html>`_ is automatically generated.
+Edit site
+=========
+
+You can write site content in Markdown instead of RST via `MyST Parser <https://myst-parser.readthedocs.io/en/latest/>`_, while still retaining the ability to write raw RST in the Markdown file for extra functionality that Markdown doesn't provide. See :ref:`markdown-test` for an example. This page was written in RST, unfortunately, since I didn't find out until after this project was complete.
+
+After creating a new file, add it to `docs/index.rst <https://github.com/NIRALUser/NeuroRuler/blob/main/docs/index.rst>`_, which is the homepage.
+
+To learn RST, see the `source code <_sources/libraries.rst.txt>`_
+for this page and `<https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html>`_.
 
 .. _sphinxBuildFromScratch:
 
-Steps for building from scratch
-===============================
+Steps for setting up from scratch
+=================================
 
 .. note:: This does not have to be done for the NR repo since setup is already complete.
     It's mostly here for my reference since there's not a lot of information about this process online and I'd forget
     how to do it.
 
-Your current working directory should be whatever repo you want to automatically generate documentation for.
+Your current working directory should be whatever repo you want to automatically generate documentation for. If you just need a local documentation site and not a public one via ReadTheDocs, skip instructions regarding ReadTheDocs.
 
 .. code-block:: text
     :linenos:
 
-    pip install sphinx
-    pip install python-docs-theme
+    pip install sphinx sphinx-rtd-theme myst_parser
     mkdir docs
     cd docs
     sphinx-quickstart
 
-Type `n` for the first question, which asks about splitting source and build directories. [#sphinx]_
+After ``sphinx-quickstart``, type `n` for the first question, which asks about splitting source and build directories. [#sphinx]_
 
-Copy over :code:`docs/conf.py` (install another theme with pip and modify :code:`html_theme` if you want),
-:code:`docs/requirements.txt`, :code:`.readthedocs.yaml`, :code:`pyproject.toml`, and :code:`setup.py` from the
-`NR repo <https://github.com/NIRALUser/NeuroRuler>`_,
-overwriting if necessary. Modify the info inside for your purposes.
-The root :code:`requirements.txt` and :code:`requirements_CI.txt` might also need to include
-setuptools, but I'm not certain.
+Run ``pip install sphinx sphinx-rtd-theme myst-parser``. Consider adding these to your ``requirements.txt``.
+Copy over :code:`docs/conf.py`
+and :code:`.readthedocs.yaml` from the `NR repo <https://github.com/NIRALUser/NeuroRuler>`_.
+Modify the info inside these files for your purposes. In ``conf.py``, you can modify
+``html_theme`` to change the website theme (you'll need to install the theme via pip).
 
-Make sure :code:`NeuroRuler/__init__.py` exists, along with :code:`.../__init__.py` files for any package that
-you want to auto-generate documentation for.
+For autodocumentation of source code, make sure :code:`NeuroRuler/__init__.py` exists, 
+along with :code:`.../__init__.py` files for any package that you want to auto-generate documentation for.
 
 .. note:: Current working directory should still be :code:`docs/`
 
@@ -567,14 +571,6 @@ You can end at Checking the first build. To set up CDD (continuous documentation
 `Permissions for connected accounts <https://docs.readthedocs.io/en/stable/guides/git-integrations.html>`_ and
 follow the `Provider-specific instructions steps <https://docs.readthedocs.io/en/stable/guides/git-integrations.html#provider-specific-instructions>`_.
 
-.. _sphinxRST:
-
-RST formatting
-==============
-
-See the `source code <_sources/libraries.rst.txt>`_
-for this page and `<https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html>`_.
-
 .. _sphinxResources:
 
 Resources

docs/markdown_test.md

@@ -0,0 +1,87 @@
+```{eval-rst}
+.. _markdown-test:
+```
+
+# This is written in Markdown
+
+```{topic} Overview
+
+This page is generated from a Markdown file via [MyST Parser](https://myst-parser.readthedocs.io/en/latest/) and also contains raw RST for extra functionality (i.e., Markdown suffices, and RST is not necessary). To view the source code for this page, click the "View page source" button at the top right.
+```
+
+```{contents}
+---
+depth: 3
+---
+```
+
+## Basic Markdown formatting
+
+*Italics*
+
+**Bold**
+
+***Italics and bold***
+
+* bulleted
+* list
+
+1. numbered
+2. list
+
+[Hyperlink](https://www.google.com)
+
+|This|is|a|table|
+|:--:|:-:|:-:|:-:|
+|0|1||3|
+
+[Referencing the below Image heading](#image)
+
+The above link generates a warning but works fine.
+
+## Code
+
+`inline code`
+
+### Multiline code with syntax highlighting
+
+```py
+import os
+for i in range(5):
+    os.system("echo echo")
+```
+
+The language is specified as `py`.
+
+## Image
+
+Below should be an image that comes from a local file.
+
+![local](_static/nr_logo.jpg)
+
+This image is from the web.
+
+![online](https://neuroruler.readthedocs.io/en/latest/_static/nr_logo.jpg)
+
+## Inline RST
+
+Below is an example of inline RST, specifically the `see-also` directive.
+
+```{seealso}
+Hello world
+```
+
+If you scroll to the very top, the overview and contents were both generated via raw RST. This uses the `myst-parser` extension. This is how to inline RST code in a Markdown file.
+
+![](_static/sphinx_markdown_rst.png)
+
+[Source](https://myst-parser.readthedocs.io/en/v0.13.3/using/syntax.html#directives-a-block-level-extension-point)
+
+The page linked above mentions that for special cases, you should use the `eval-rst` directive instead.
+
+![eval-rst](_static/eval_rst.png)
+
+For example, the source for this page uses an RST directive on the first line.
+
+Remember to add your page to `index.rst` (including the `.md` extension), and run `make html` to build the HTML.
+

requirements.txt

@@ -10,10 +10,9 @@
  # .
 
 # Additional non-functional dependencies (e.g., formatting, documentation) for developers
-
 sphinx
 sphinx_rtd_theme
-m2r2
+myst_parser
 ipywidgets
 black
 black[jupyter]