Improve Python reference documentation (#1209)

* Improve Python reference documentation
* Fix lint
* Add some missing docstrings
* Use new ReadTheDocs config format, bake sphinx dependencies and move to MyST
* Re-generate plugins and schema docs
* Add spatial coordinates doc to main doctree
* Simplify the process for building the docs locally
* Fix Sphinx warnings
* enable GH builds
* Modify make.bat to match with the docs Makefile
* Add job to detect doc warnings/errors

Signed-off-by: Jean-Christophe Morin <[email protected]>

.github/workflows/docs.yml

@@ -0,0 +1,105 @@
+name: docs
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  check-links:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        submodules: 'recursive'
+
+    - uses: actions/setup-python@v3
+      with:
+        python-version: '3.10'
+
+    - name: Create virtualenv
+      run: python3 -m venv .venv
+
+    - name: Install dependencies
+      run: |
+        source .venv/bin/activate
+        python -m pip install .
+        python -m pip install -r docs/requirements.txt
+
+    - name: Linkcheck
+      working-directory: docs
+      run: |
+        source ../.venv/bin/activate
+
+        set +e
+        make linkcheck
+        exit_code=$?
+
+        set -e
+
+        if [ $exit_code -eq 0 ]; then
+            echo -e "\n\n=================\nAll links are valid!"
+
+            echo "# :heavy_check_mark: Sphinx links" >> $GITHUB_STEP_SUMMARY
+            echo "All links are valid!" >> $GITHUB_STEP_SUMMARY
+        else
+            echo -e "\n\n=================\nFound broken links. Look at the build logs.\n"
+
+            echo "# :x: Sphinx links" >> $GITHUB_STEP_SUMMARY
+            echo "Found broken links. Look at the build logs for additional information." >> $GITHUB_STEP_SUMMARY
+            echo '```' >> $GITHUB_STEP_SUMMARY
+            cat _build/linkcheck/output.txt >> $GITHUB_STEP_SUMMARY
+            echo '```' >> $GITHUB_STEP_SUMMARY
+        fi
+
+        exit $exit_code
+
+  check-warnings:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        submodules: 'recursive'
+
+    - uses: actions/setup-python@v3
+      with:
+        python-version: '3.10'
+
+    - name: Create virtualenv
+      run: python3 -m venv .venv
+
+    - name: Install dependencies
+      run: |
+        source .venv/bin/activate
+        python -m pip install .
+        python -m pip install -r docs/requirements.txt
+
+    - name: Check warnings/errors
+      working-directory: docs
+      run: |
+        source ../.venv/bin/activate
+
+        set +e
+        make htmlstrict
+
+        exit_code=$?
+
+        set -e
+
+        if [ $exit_code -eq 0 ]; then
+            echo -e "\n\n=================\nNo warnings or errors detected!"
+            echo "# :heavy_check_mark: Sphinx warnings/errors" >> $GITHUB_STEP_SUMMARY
+            echo "No errors or warnings detected!" >> $GITHUB_STEP_SUMMARY
+        else
+            echo -e "\n\n=================\nWarnings and or errors detected; See the summary bellow:\n"
+            cat _build/htmlstrict/output.txt
+
+            echo "# :x: Sphinx warnings/errors" >> $GITHUB_STEP_SUMMARY
+            echo "Found some warnings or errors:" >> $GITHUB_STEP_SUMMARY
+            echo '```' >> $GITHUB_STEP_SUMMARY
+            cat _build/htmlstrict/output.txt >> $GITHUB_STEP_SUMMARY
+            echo '```' >> $GITHUB_STEP_SUMMARY
+        fi
+
+        exit $exit_code

.gitignore

@@ -16,4 +16,5 @@ xcuserdata/
 
 # These files are generated, don't put them into source control
 docs/api
+docs/_build
 .tox

.readthedocs.yml

@@ -2,19 +2,16 @@
 version: 2
 
 build:
-  image: latest
+  os: "ubuntu-20.04"
+  tools:
+    python: "3.10"
 
 python:
-  version: 3.7
   install:
-    - method: pip
-      path: .
-      extra_requirements:
-        - cmake
+  - method: pip
+    path: .
+  - requirements: docs/requirements.txt
 
 submodules:
   include: all
   recursive: true
-
-conda:
-  environment: readthedocs-conda.yml

Makefile

@@ -20,7 +20,6 @@ $(ccblue)	pip install -e .[dev]$(newline)$(ccend)
 endef
 
 # variables
-DOC_OUTPUT_DIR ?= /var/tmp/otio-docs
 MAKE_PROG ?= make
 
 # external programs
@@ -117,6 +116,7 @@ ifdef COV_PROG
 endif
 	@${MAKE_PROG} -C contrib/opentimelineio_contrib/adapters clean VERBOSE=$(VERBOSE)
 	rm -vf *.whl
+	@cd docs; ${MAKE_PROG} clean
 
 # conform all files to pep8 -- WILL CHANGE FILES IN PLACE
 # autopep8:
@@ -185,8 +185,7 @@ doc-plugins-update:
 # generate documentation in html
 doc-html:
 	@# if you just want to build the docs yourself outside of RTD
-	@echo "Writing documentation to $(DOC_OUTPUT_DIR), set variable DOC_OUTPUT_DIR to change output directory."
-	@cd docs ; sphinx-build -j8 -E -b html -d $(DOC_OUTPUT_DIR)/doctrees . $(DOC_OUTPUT_DIR)/html
+	@cd docs; ${MAKE_PROG} html
 
 doc-cpp: 
 	@cd doxygen ; doxygen config/dox_config ; cd .. 

docs/Makefile

@@ -2,22 +2,23 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -n -j8
 SPHINXBUILD   = sphinx-build
 PAPER         =
-BUILDDIR      = build
+BUILDDIR      = _build
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
 
 .PHONY: help
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html       to make standalone HTML files"
+	@echo "  htmlstrict to make standalone HTML files and fails if any warnings or errors are produced"
 	@echo "  dirhtml    to make HTML files named index.html in directories"
 	@echo "  singlehtml to make a single large HTML file"
 	@echo "  pickle     to make pickle files"
@@ -54,6 +55,12 @@ html:
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
+.PHONY: htmlstrict
+htmlstrict:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/htmlstrict -W --keep-going -w $(BUILDDIR)/htmlstrict/output.txt
+	@echo
+	@echo "Warnings check complete."
+
 .PHONY: dirhtml
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml

docs/_templates/autosummary/module.rst

@@ -0,0 +1,18 @@
+{{ fullname }}
+{{ underline }}
+
+.. automodule:: {{ fullname }}
+    :members:
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}