Documentation site build rework

.github/CONTRIBUTING.md

@@ -66,15 +66,15 @@ The homepage source code is in `./docs/source/index.rst`.
 To build the documentation locally (not required but good check)
 
 ```bash
-cd docs
-make html
+python3 docs/build_docs.py
 ```
 
 The built documentation will be in `./docs/_build` and the homepage is `./docs/_build/index.html`.
-To delete do `make clean`.
+To delete, do `python3 docs/clean_docs.py`.
 
 The documentation uses the Jupyter notebook tutorials in the `examples` directory.
 When building the documentation locally you will need to have installed [pandoc](https://pandoc.org/installing.html) and [gifsicle](https://github.com/kohler/gifsicle).
+We recommend installing pandoc using its Anaconda distribution: `conda install -c conda-forge pandoc`.
 
 ### Editing the tutorials
 The tutorials are used as part of the Documentation.

.github/workflows/release.yml

@@ -62,10 +62,7 @@ jobs:
     - name: Build documentation
       shell: bash -l {0}
       run: |
-        cd docs
-        make linkcheck
-        make html
-        cd ../
+        python3 docs/build_docs.py
 
     - name: Deploy
       uses: peaceiris/actions-gh-pages@v3

docs/build_docs.py

@@ -0,0 +1,39 @@
+import os
+from shutil import rmtree
+import source.make_theory_animations
+from sphinx.application import Sphinx
+
+docs_dir = os.path.dirname(os.path.abspath(__file__))
+source_dir = os.path.join(docs_dir, 'source')
+conf_dir = source_dir
+build_dir = os.path.join(docs_dir, '_build')
+doctree_dir = os.path.join(build_dir, '.doctrees')
+example_dir = os.path.join(source_dir, '_examples')
+api_dir = os.path.join(source_dir, 'api_docs')
+
+
+def linkcheck():
+    app = Sphinx(source_dir,
+                 conf_dir,
+                 build_dir,
+                 doctree_dir,
+                 'linkcheck',
+                 warningiserror=True)
+    app.build()
+
+
+def html():
+    app = Sphinx(source_dir,
+                 conf_dir,
+                 build_dir,
+                 doctree_dir,
+                 'html',
+                 warningiserror=True)
+
+    app.build()
+
+
+if __name__ == '__main__':
+    source.make_theory_animations
+    linkcheck()
+    html()

docs/clean_docs.py

@@ -0,0 +1,14 @@
+import os
+from shutil import rmtree
+
+docs_dir = os.path.dirname(os.path.abspath(__file__))
+source_dir = os.path.join(docs_dir, 'source')
+example_dir = os.path.join(source_dir, '_examples')
+api_dir = os.path.join(source_dir, 'api_docs')
+
+def clean():
+    rmtree(example_dir)
+    rmtree(api_dir)
+
+if __name__ == '__main__':
+    clean()

docs/source/conf.py

@@ -52,10 +52,14 @@
 def setup(app):
     app.add_css_file('css/custom.css')
 
-suppress_warnings = ["autosectionlabel.*"] # nbsphinx and austosectionlabel do not play well together
+suppress_warnings = ['autosectionlabel.*', # nbsphinx and austosectionlabel do not play well together
+                     'app.add_node', # using multiple builders in custom Sphinx objects throws a bunch of these
+                     'app.add_directive',
+                     'app.add_role',]
 
 linkcheck_ignore = [
     'https://github.com/HIPS/autograd/blob/master/docs/tutorial.md#supported-and-unsupported-parts-of-numpyscipy',
+    'https://www.osti.gov/biblio/1330189/',
 ]
 
 # -- References (BibTex) -----------------------------------------------------

wecopttool/geom.py

@@ -24,7 +24,7 @@ class WaveBot:
     See, e.g.,
 
         - https://doi.org/10.3390/en10040472
-        - https://doi.org/10.2172/1330189
+        - https://www.osti.gov/biblio/1330189/
 
     """