Add AutoAPI (sio2project#216)

- add autoapi module
- make list of modules compile on readthedocs too

rst/Makefile

@@ -35,41 +35,38 @@ help:
 clean:
 	-rm -rf $(BUILDDIR)/*
 
-autogen:
-	python3 gendoc.py
-
-html: autogen
+html: 
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
-dirhtml: autogen
+dirhtml: 
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
-singlehtml: autogen
+singlehtml: 
 	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
-pickle: autogen
+pickle: 
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 
-json: autogen
+json: 
 	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
-htmlhelp: autogen
+htmlhelp: 
 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in $(BUILDDIR)/htmlhelp."
 
-qthelp: autogen
+qthelp: 
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
@@ -78,7 +75,7 @@ qthelp: autogen
 	@echo "To view the help file:"
 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/OIOIOI.qhc"
 
-devhelp: autogen
+devhelp: 
 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
 	@echo
 	@echo "Build finished."
@@ -87,46 +84,46 @@ devhelp: autogen
 	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/OIOIOI"
 	@echo "# devhelp"
 
-epub: autogen
+epub: 
 	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
 
-latex: autogen
+latex: 
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
 	@echo "Run \`make' in that directory to run these through (pdf)latex" \
 	      "(use \`make latexpdf' here to do that automatically)."
 
-latexpdf: autogen
+latexpdf: 
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through pdflatex..."
 	make -C $(BUILDDIR)/latex all-pdf
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
-text: autogen
+text: 
 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
 	@echo
 	@echo "Build finished. The text files are in $(BUILDDIR)/text."
 
-man: autogen
+man: 
 	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
 	@echo
 	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
 
-changes: autogen
+changes: 
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
 	@echo
 	@echo "The overview file is in $(BUILDDIR)/changes."
 
-linkcheck: autogen
+linkcheck: 
 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in $(BUILDDIR)/linkcheck/output.txt."
 
-doctest: autogen
+doctest: 
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/doctest/output.txt."

rst/requirements.txt

@@ -1,2 +1,3 @@
 sphinx==4.2.0
 furo==2021.9.22  # sphinx theme https://github.com/pradyunsg/furo
+sphinx-autoapi==2.1.0  # sphinx extension https://sphinx-autoapi.readthedocs.io/en/latest/index.html

rst/source/conf.py

@@ -29,11 +29,37 @@
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
-    'sphinx.ext.autodoc',
+    'sphinx.ext.autodoc',  # Also required by AutoAPI.
     'sphinx.ext.coverage',
     'sphinx.ext.viewcode',
+    'autoapi.extension'
 ]
 
+# Setup AutoAPI
+# https://sphinx-autoapi.readthedocs.io/en/latest/
+autoapi_dirs = ['../../oioioi/']
+
+# Keeping files will allow AutoAPI to use incremental builds. However, this means that when a module is deleted and then
+# docs are built locally, the corresponding files in autoapi/ (or the entire autoapi/ directory) need to be deleted.
+#
+# The public docs are built from scratch every time, so it's not a problem there.
+# autoapi_keep_files = True
+
+# Exclude migrations and tests.
+# Based on https://sphinx-autoapi.readthedocs.io/en/latest/how_to.html#connect-to-the-autoapi-skip-member-event.
+def should_skip_submodule(app, what, name, obj, skip, options):
+    submodule = name.split(".")[-1]
+    if submodule in ["migrations", "tests"]:
+        skip = True
+    return skip
+
+def setup(sphinx):
+    import gendoc  # This will generate the list of modules.
+
+    # Note: doing the same with autodoc-skip-member will make builds fail.
+    sphinx.connect("autoapi-skip-member", should_skip_submodule)
+
+
 autodoc_member_order = 'bysource'
 
 # Add any paths that contain templates here, relative to this directory.

rst/gendoc.py → rst/source/gendoc.py

@@ -9,7 +9,7 @@
 import os
 import sys
 
-sys.path.append("../")
+sys.path.append("../../")
 
 import oioioi