Merge pull request #43 from csiro-coasts/docs-improvements

Docs improvements

.github/workflows/ci.yaml

@@ -84,12 +84,12 @@ jobs:
 
       - run: |
           cd docs/
-          sphinx-build -b html -aEW . _build/html
+          sphinx-build -b dirhtml -aEW . _build/dirhtml
 
       - uses: actions/upload-artifact@v3
         with:
           name: Docs
-          path: docs/_build/html
+          path: docs/_build/dirhtml
 
   package:
     runs-on: ubuntu-latest

.readthedocs.yaml

@@ -7,6 +7,7 @@ build:
 
 sphinx:
   configuration: "docs/conf.py"
+  builder: "dirhtml"
 
 conda:
   environment: continuous-integration/docs.yaml

docs/Makefile

@@ -28,5 +28,5 @@ WATCH_ARGS=-rq \
 	$(patsubst %,@%,$(WATCH_IGNORE))
 
 live:
-	$(MAKE) SPHINXOPTS="-j auto" html
+	$(MAKE) SPHINXOPTS="-j auto" dirhtml
 	python3 ./live.py

docs/api/operations/index.rst

@@ -13,18 +13,18 @@ and behave the same across all supported formats.
 
    ./*
 
-:mod:`emsarray.operations.depth`
+:doc:`depth`
     These operations manipulate datasets with a depth axis,
     such as the output of ocean models.
 
-:mod:`emsarray.operations.geometry`
+:doc:`geometry`
     These operations export the geometry of a dataset
     in a variety of different formats.
 
-:mod:`emsarray.operations.point_extraction`
+:doc:`point_extraction`
     Functions to extract data from a dataset at a collection of points.
 
-:mod:`emsarray.operations.triangulate`
+:doc:`triangulate`
     These operations triangulate the polygonal mesh of a dataset.
     This is useful in combination with visualisation packages such as
     Trimesh or Holoviews.

docs/conf.py

@@ -63,6 +63,9 @@
 html_static_path = ['_static']
 
 
+add_module_names = False
+
+
 napoleon_google_docstring = False
 napoleon_numpy_docstring = True
 napoleon_use_param = False

docs/developing/formats.rst

@@ -20,7 +20,7 @@ called ``grass``.
 
 To add support for GRASS to ``emsarray``, make a new Format subclass.
 For this example, we will make a new module named ``grass.format``.
-The complete implementation of the :ref:`Grass class is available <grass_code>`.
+The complete implementation of the :download:`Grass class is available <./grass.py>`.
 The following is a guided walk through developing this class.
 
 We will need the following imports:

docs/live.py

@@ -4,12 +4,13 @@
 
 
 def main() -> None:
+    command = shell('make dirhtml')
     server = Server()
-    server.watch('**/*.rst', shell('make html'), delay=0.1)
-    server.watch('**/*.py', shell('make html'), delay=0.1)
-    server.watch('**/*.ipynb', shell('make html'), delay=0.1)
-    server.watch('../src', shell('make html'), delay=0.1)
-    server.serve(root='./_build/html')
+    server.watch('**/*.rst', command, delay=0.1)
+    server.watch('**/*.py', command, delay=0.1)
+    server.watch('**/*.ipynb', command, delay=0.1)
+    server.watch('../src', command, delay=0.1)
+    server.serve(root='./_build/dirhtml')
 
 
 if __name__ == '__main__':