add better API docs (#31)

Author: zingale

.github/workflows/docs-test.yml

@@ -0,0 +1,41 @@
+name: docs build
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+env:
+  # enable color output from Sphinx
+  FORCE_COLOR: "1"
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install pandoc and doxygen
+        run: |
+          sudo apt install pandoc doxygen
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: "pip"
+
+      - name: Install dependencies
+        run: pip install -r ./requirements.txt
+
+      - name: Install ppmpy
+        run: pip install --editable .
+
+      - name: Build docs
+        run: |
+          jupyter-book build --all ./docs

.gitignore

@@ -8,6 +8,9 @@ __pycache__
 *.exe
 
 _build.*
+_build
+
+flycheck*
 
 *.pdf
 

docs/README.md

@@ -0,0 +1,3 @@
+To generate the API docs, from the root directory, do:
+
+sphinx-apidoc -f -M  -e -o docs ppmpy

docs/_toc.yml

@@ -18,4 +18,5 @@ parts:
 
   - caption: API
     chapters:
-    - file: api.rst
+    - file: ppmpy.rst
+

docs/modules.rst

@@ -0,0 +1,7 @@
+ppmpy
+=====
+
+.. toctree::
+   :maxdepth: 4
+
+   ppmpy

docs/ppmpy.advection.rst

@@ -0,0 +1,7 @@
+ppmpy.advection module
+======================
+
+.. automodule:: ppmpy.advection
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/ppmpy.eigen.rst

@@ -0,0 +1,7 @@
+ppmpy.eigen module
+==================
+
+.. automodule:: ppmpy.eigen
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/ppmpy.euler.rst

@@ -0,0 +1,7 @@
+ppmpy.euler module
+==================
+
+.. automodule:: ppmpy.euler
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/ppmpy.gravity.rst

@@ -0,0 +1,7 @@
+ppmpy.gravity module
+====================
+
+.. automodule:: ppmpy.gravity
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/ppmpy.grid.rst

@@ -0,0 +1,7 @@
+ppmpy.grid module
+=================
+
+.. automodule:: ppmpy.grid
+   :members:
+   :undoc-members:
+   :show-inheritance: