doc improvements and private submodules

private submodules prevent sphinx-apidoc from double documenting items
wolearyc · Oct 3, 2024 · c20fa41 · c20fa41
1 parent a6786f6
commit c20fa41
Show file tree

Hide file tree

Showing 53 changed files with 206 additions and 293 deletions.
diff --git a/docs/gen_api_sources.sh b/docs/gen_api_sources.sh
@@ -1,2 +1,2 @@
-# CD must be the reports directory!
-sphinx-apidoc -o source/generated ../ramannoodle
+# CD must be the docs directory
+sphinx-apidoc --module-first --remove-old -f --templatedir=source/_templates -f  --remove-old -o source/generated ../ramannoodle
diff --git a/docs/gen_test_coverage_badges.sh b/docs/gen_test_coverage_badges.sh
@@ -1,4 +1,4 @@
-# CD must be the reports directory!
+# CD must be the docs directory!
 cd ..
 coverage run -m pytest --junitxml=reports/junit/junit.xml test
 coverage xml -o  reports/coverage/coverage.xml

diff --git a/docs/source/_templates/module.rst.jinja b/docs/source/_templates/module.rst.jinja
@@ -0,0 +1,8 @@
+{%- if show_headings %}
+{{- [basename, "module"] | join(' ') | e | heading }}
+
+{% endif -%}
+.. automodule:: {{ qualname }}
+{%- for option in automodule_options %}
+   :{{ option }}:
+{%- endfor %}
diff --git a/docs/source/_templates/package.rst.jinja b/docs/source/_templates/package.rst.jinja
@@ -0,0 +1,57 @@
+{%- macro automodule(modname, options) -%}
+.. automodule:: {{ modname }}
+{%- for option in options %}
+   :{{ option }}:
+{%- endfor %}
+{%- endmacro %}
+
+{%- macro toctree(docnames) -%}
+.. toctree::
+   :maxdepth: {{ maxdepth }}
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}
+{%- endmacro %}
+
+{%- if is_namespace %}
+{{- [pkgname, ""] | join(" ") | e | heading }}
+{% else %}
+{{- [pkgname, ""] | join(" ") | e | heading }}
+{% endif %}
+
+{%- if is_namespace %}
+.. py:module:: {{ pkgname }}
+{% endif %}
+
+{%- if modulefirst and not is_namespace %}
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}
+
+{%- if subpackages %}
+Subpackages
+-----------
+
+{{ toctree(subpackages) }}
+{% endif %}
+
+{%- if submodules %}
+Submodules
+----------
+{% if separatemodules %}
+{{ toctree(submodules) }}
+{% else %}
+{%- for submodule in submodules %}
+{% if show_headings %}
+{{- [submodule, "module"] | join(" ") | e | heading(2) }}
+{% endif %}
+{{ automodule(submodule, automodule_options) }}
+{% endfor %}
+{%- endif %}
+{%- endif %}
+
+{%- if not modulefirst and not is_namespace %}
+Module contents
+---------------
+
+{{ automodule(pkgname, automodule_options) }}
+{% endif %}
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -38,6 +38,7 @@
     'numpy': ('http://docs.scipy.org/doc/numpy', None),
     'scipy': ('http://docs.scipy.org/doc/scipy/reference', None),
     'torch': ('https://pytorch.org/docs/stable/', None),
+    'pymatgen': ('https://pymatgen.org', None),
 }
 
 intersphinx_disabled_domains = ['std']

diff --git a/docs/source/generated/ramannoodle.dataset.rst b/docs/source/generated/ramannoodle.dataset.rst
@@ -1,5 +1,10 @@
-ramannoodle.dataset package
-===========================
+ramannoodle.dataset
+====================
+
+.. automodule:: ramannoodle.dataset
+   :members:
+   :undoc-members:
+   :show-inheritance:
 
 Subpackages
 -----------
@@ -8,11 +13,3 @@ Subpackages
    :maxdepth: 4
 
    ramannoodle.dataset.torch
-
-Module contents
----------------
-
-.. automodule:: ramannoodle.dataset
-   :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/generated/ramannoodle.dataset.torch.rst b/docs/source/generated/ramannoodle.dataset.torch.rst
@@ -1,29 +1,18 @@
-ramannoodle.dataset.torch package
-=================================
+ramannoodle.dataset.torch
+==========================
 
-Submodules
-----------
-
-ramannoodle.dataset.torch.dataset module
-----------------------------------------
-
-.. automodule:: ramannoodle.dataset.torch.dataset
+.. automodule:: ramannoodle.dataset.torch
    :members:
    :undoc-members:
    :show-inheritance:
 
+Submodules
+----------
+
 ramannoodle.dataset.torch.utils module
 --------------------------------------
 
 .. automodule:: ramannoodle.dataset.torch.utils
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: ramannoodle.dataset.torch
-   :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/generated/ramannoodle.dynamics.rst b/docs/source/generated/ramannoodle.dynamics.rst
@@ -1,27 +1,5 @@
-ramannoodle.dynamics package
-============================
-
-Submodules
-----------
-
-ramannoodle.dynamics.phonon module
-----------------------------------
-
-.. automodule:: ramannoodle.dynamics.phonon
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-ramannoodle.dynamics.trajectory module
---------------------------------------
-
-.. automodule:: ramannoodle.dynamics.trajectory
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-Module contents
----------------
+ramannoodle.dynamics
+=====================
 
 .. automodule:: ramannoodle.dynamics
    :members:

diff --git a/docs/source/generated/ramannoodle.io.rst b/docs/source/generated/ramannoodle.io.rst
@@ -1,5 +1,10 @@
-ramannoodle.io package
-======================
+ramannoodle.io
+===============
+
+.. automodule:: ramannoodle.io
+   :members:
+   :undoc-members:
+   :show-inheritance:
 
 Subpackages
 -----------
@@ -20,18 +25,10 @@ ramannoodle.io.generic module
    :undoc-members:
    :show-inheritance:
 
-ramannoodle.io.utils module
----------------------------
+ramannoodle.io.pymatgen module
+------------------------------
 
-.. automodule:: ramannoodle.io.utils
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: ramannoodle.io
+.. automodule:: ramannoodle.io.pymatgen
    :members:
    :undoc-members:
    :show-inheritance:
diff --git a/docs/source/generated/ramannoodle.io.vasp.rst b/docs/source/generated/ramannoodle.io.vasp.rst
@@ -1,5 +1,10 @@
-ramannoodle.io.vasp package
-===========================
+ramannoodle.io.vasp
+====================
+
+.. automodule:: ramannoodle.io.vasp
+   :members:
+   :undoc-members:
+   :show-inheritance:
 
 Submodules
 ----------
@@ -35,11 +40,3 @@ ramannoodle.io.vasp.xdatcar module
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: ramannoodle.io.vasp
-   :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/generated/ramannoodle.pmodel.rst b/docs/source/generated/ramannoodle.pmodel.rst
@@ -1,5 +1,10 @@
-ramannoodle.pmodel package
-==========================
+ramannoodle.pmodel
+===================
+
+.. automodule:: ramannoodle.pmodel
+   :members:
+   :undoc-members:
+   :show-inheritance:
 
 Subpackages
 -----------
@@ -8,30 +13,3 @@ Subpackages
    :maxdepth: 4
 
    ramannoodle.pmodel.torch
-
-Submodules
-----------
-
-ramannoodle.pmodel.art module
------------------------------
-
-.. automodule:: ramannoodle.pmodel.art
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-ramannoodle.pmodel.interpolation module
----------------------------------------
-
-.. automodule:: ramannoodle.pmodel.interpolation
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: ramannoodle.pmodel
-   :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/generated/ramannoodle.pmodel.torch.rst b/docs/source/generated/ramannoodle.pmodel.torch.rst
@@ -1,35 +1,5 @@
-ramannoodle.pmodel.torch package
-================================
-
-Submodules
-----------
-
-ramannoodle.pmodel.torch.gnn module
------------------------------------
-
-.. automodule:: ramannoodle.pmodel.torch.gnn
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-ramannoodle.pmodel.torch.train module
--------------------------------------
-
-.. automodule:: ramannoodle.pmodel.torch.train
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-ramannoodle.pmodel.torch.utils module
--------------------------------------
-
-.. automodule:: ramannoodle.pmodel.torch.utils
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-Module contents
----------------
+ramannoodle.pmodel.torch
+=========================
 
 .. automodule:: ramannoodle.pmodel.torch
    :members:

diff --git a/docs/source/generated/ramannoodle.rst b/docs/source/generated/ramannoodle.rst
@@ -1,5 +1,10 @@
-ramannoodle package
-===================
+ramannoodle
+============
+
+.. automodule:: ramannoodle
+   :members:
+   :undoc-members:
+   :show-inheritance:
 
 Subpackages
 -----------
@@ -40,11 +45,3 @@ ramannoodle.exceptions module
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: ramannoodle
-   :members:
-   :undoc-members:
-   :show-inheritance:
diff --git a/docs/source/generated/ramannoodle.spectrum.rst b/docs/source/generated/ramannoodle.spectrum.rst
@@ -1,29 +1,18 @@
-ramannoodle.spectrum package
-============================
+ramannoodle.spectrum
+=====================
 
-Submodules
-----------
-
-ramannoodle.spectrum.raman module
----------------------------------
-
-.. automodule:: ramannoodle.spectrum.raman
+.. automodule:: ramannoodle.spectrum
    :members:
    :undoc-members:
    :show-inheritance:
 
+Submodules
+----------
+
 ramannoodle.spectrum.utils module
 ---------------------------------
 
 .. automodule:: ramannoodle.spectrum.utils
    :members:
    :undoc-members:
    :show-inheritance:
-
-Module contents
----------------
-
-.. automodule:: ramannoodle.spectrum
-   :members:
-   :undoc-members:
-   :show-inheritance: