feat!: modernize documentation setup

This commit autodocuments Ion apps (removing the need for a script), and
fixes many of the formatting errors in the current docs.
It also updates the docs for the formatting/linting CI, which was
updated in #1659

.github/workflows/ci.yml

@@ -118,9 +118,13 @@
                     "if": "github.event_name == 'push' && (github.repository_owner != 'tjcsl' || github.ref != 'refs/heads/master' || github.ref != 'refs/heads/dev')",
                     "run": "git fetch origin ${{ github.event.before }} && ./scripts/validate-commit-messages.py ${{ github.event.before }}..${{ github.event.after }}"
                 },
+                {
+                    "name": "Install docs dependencies",
+                    "run": "# sphinxcontrib_django imports our django project, so we need the deps\npip install -U -r requirements.txt\ncd docs\npip install -U -r requirements.txt\n"
+                },
                 {
                     "name": "Build docs",
-                    "run": "./scripts/build_ensure_no_changes.sh ./scripts/build_docs.sh"
+                    "run": "make html"
                 },
                 {
                     "name": "Push docs",

.gitignore

@@ -9,6 +9,7 @@ Pipfile
 build
 .coverage
 dist/*.tar.gz
+docs/source/reference
 
 # General ignores
 *.crt

README.rst

@@ -20,10 +20,10 @@ Documentation (in RestructuredText format) is available inside the "docs" folder
 
 **Ion now requires Python 3.8+** Python 3.8.5 is currently used in both production and testing environments.
 
-**How can I create a testing environment?** Read the section on `Setting up a Dev Environment <https://github.com/tjcsl/ion/blob/master/SETUP.md>`_ in the documentation.
+**How can I create a testing environment?** Read the section on `Setting up a Dev Environment <https://tjcsl.github.io/ion/setup/setup.html>`_ in the documentation.
 
 **How can I contribute to Ion? How can I report a bug? How can I report a security issue/vulnerability?**
 
-Please read our `contributing guide <https://github.com/tjcsl/ion/blob/master/CONTRIBUTING.md>`_ for more information.
+Please read our `contributing guide <https://tjcsl.github.io/ion/developing/contributing.html>`_ for more information.
 
 Current Intranet maintainers: `alanzhu0 <https://github.com/alanzhu0>`_ and `NotFish232 <https://github.com/NotFish232>`_

ci/spec.yml

@@ -119,8 +119,16 @@ jobs:
         run: 'git fetch origin ${{ github.event.before }} && ./scripts/validate-commit-messages.py ${{ github.event.before }}..${{ github.event.after }}'
 
       # Build/push docs
+      - name: Install docs dependencies
+        run: |
+          # sphinxcontrib_django imports our django project, so we need the deps
+          pip install -U -r requirements.txt
+          cd docs
+          pip install -U -r requirements.txt
+
       - name: Build docs
-        run: ./scripts/build_ensure_no_changes.sh ./scripts/build_docs.sh
+        run: make html
+
       - name: Push docs
         # Only run for pushes to the main Ion repo
         if: github.event_name == 'push' && github.ref == 'refs/heads/master' && github.repository_owner == 'tjcsl' && matrix.python-version == 3.8

docs/Makefile

@@ -0,0 +1,24 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+cleanall: clean
+	@echo "Cleaning all references"
+	@rm source/reference/*
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/requirements.txt

@@ -0,0 +1,4 @@
+furo
+myst-parser
+sphinx-copybutton
+sphinxcontrib-django

docs/source/_templates/autosummary/class.rst

@@ -0,0 +1,34 @@
+{{ name | escape | underline}}
+
+Qualified name: ``{{ fullname | escape }}``
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :show-inheritance:
+   :members:
+   :private-members:
+
+
+   {% block methods %}
+   {%- if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      :nosignatures:
+      {% for item in methods if item != '__init__' and item[0] != '_' and item not in inherited_members %}
+      ~{{ name }}.{{ item }}
+      {%- endfor %}
+   {%- endif %}
+   {%- endblock %}
+
+   {% block attributes %}
+   {%- if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+     {% for item in attributes if item[0] != '_' and item not in inherited_members %}
+     ~{{ name }}.{{ item }}
+     {%- endfor %}
+   {%- endif %}
+   {% endblock %}

docs/source/_templates/autosummary/module.rst

@@ -0,0 +1,52 @@
+{{ name | escape | underline }}
+
+.. currentmodule:: {{ fullname }}
+
+.. automodule:: {{ fullname }}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: Classes
+
+   .. autosummary::
+      :toctree: .
+      :nosignatures:
+      {% for class in classes %}
+        {{ class }}
+      {% endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   {% for item in functions %}
+   .. autofunction:: {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}