Automatically generate the sphinx toctree in pre-commit.

glotzerlab · Nov 26, 2024 · 2a07041 · 2a07041
1 parent 1f4cb0c
commit 2a07041
Show file tree

Hide file tree

Showing 8 changed files with 15 additions and 12 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -17,6 +17,16 @@ repos:
     entry: '(# Maintainer:|\/\/ Maintainer:)'
     language: pygrep
     types_or: [python, c, c++, cuda, inc]
+- repo: local
+  hooks:
+  - id: generate_toctree
+    name: Generate Sphinx toctree
+    language: python
+    entry: python3 sphinx-doc/generate-toctree.py
+    pass_filenames: false
+    always_run: true
+    additional_dependencies:
+     - numpy==2.1.0
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: 'v5.0.0'
   hooks:

diff --git a/sphinx-doc/generate-toctree.py b/sphinx-doc/generate-toctree.py
@@ -98,7 +98,8 @@ def generate_module_rst(path, module):
     module_rst = f"{module_name}\n{module_underline}\n\n"
     module_rst += f".. automodule:: {full_module_name}\n"
     module_rst += "   :members:\n"
-    module_rst += f"   :exclude-members: {','.join(classes + functions)}\n\n"
+    if len(classes) > 0 or len(functions) > 0:
+        module_rst += f"   :exclude-members: {','.join(classes + functions)}\n\n"
 
     if len(submodules) > 0:
         module_rst += '.. rubric:: Modules\n\n.. toctree::\n    :maxdepth: 1\n\n'
@@ -119,6 +120,9 @@ def generate_module_rst(path, module):
             module_rst += f'    {module_name}/{function_name.lower()}\n'
         module_rst += '\n'
 
+    # ensure there is only one newline at the end of the file
+    module_rst = module_rst.rstrip()
+    module_rst += '\n'
     file = (path.parent / ('module-' + module_name)).with_suffix('.rst')
     file.write_text(module_rst)
 

diff --git a/sphinx-doc/hoomd/hpmc/module-nec.rst b/sphinx-doc/hoomd/hpmc/module-nec.rst
@@ -3,8 +3,6 @@ nec
 
 .. automodule:: hoomd.hpmc.nec
    :members:
-   :exclude-members:
-
 .. rubric:: Modules
 
 .. toctree::

diff --git a/sphinx-doc/hoomd/md/module-alchemy.rst b/sphinx-doc/hoomd/md/module-alchemy.rst
@@ -3,8 +3,6 @@ alchemy
 
 .. automodule:: hoomd.md.alchemy
    :members:
-   :exclude-members:
-
 .. rubric:: Modules
 
 .. toctree::

diff --git a/sphinx-doc/hoomd/md/module-external.rst b/sphinx-doc/hoomd/md/module-external.rst
@@ -3,8 +3,6 @@ external
 
 .. automodule:: hoomd.md.external
    :members:
-   :exclude-members:
-
 .. rubric:: Modules
 
 .. toctree::

diff --git a/sphinx-doc/hoomd/md/module-long_range.rst b/sphinx-doc/hoomd/md/module-long_range.rst
@@ -3,8 +3,6 @@ long_range
 
 .. automodule:: hoomd.md.long_range
    :members:
-   :exclude-members:
-
 .. rubric:: Modules
 
 .. toctree::

diff --git a/sphinx-doc/hoomd/module-hpmc.rst b/sphinx-doc/hoomd/module-hpmc.rst
@@ -3,8 +3,6 @@ hpmc
 
 .. automodule:: hoomd.hpmc
    :members:
-   :exclude-members:
-
 .. rubric:: Modules
 
 .. toctree::

diff --git a/sphinx-doc/hoomd/module-version.rst b/sphinx-doc/hoomd/module-version.rst
@@ -3,4 +3,3 @@ version
 
 .. automodule:: hoomd.version
    :members:
-   :exclude-members: