Document one class per html page and list all inherited members.

.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:
@@ -40,7 +50,7 @@ repos:
           ^sphinx-doc/tutorial/|
           ^sphinx-doc/howto/
           )
-    types_or: [python, c, c++, cuda, inc, rst]
+    types_or: [python, c, c++, cuda, inc]
     args:
     - --license-file=LICENSE
     - --add=Part of HOOMD-blue, released under the BSD 3-Clause License.
@@ -68,6 +78,11 @@ repos:
     # These also need to be removed in setup.cfg
     exclude: |
       (?x)(
+        ^hoomd/_hoomd.py|
+        ^hoomd/version_config.py|
+        ^hoomd/md/_md.py|
+        ^hoomd/hpmc/_hpmc.py|
+        ^hoomd/mpcd/_mpcd.py|
         ^hoomd/extern/|
         ^hoomd/metal/
       )

ARCHITECTURE.md

@@ -18,7 +18,7 @@ Each minor and major release of HOOMD-blue at a minimum supports:
 
 ### Continuous integration
 
-[Github Actions] performs continuous integration testing on HOOMD-blue. GitHub
+[GitHub Actions] performs continuous integration testing on HOOMD-blue. GitHub
 Actions compiles HOOMD-blue, runs the unit tests, and reports the
 status to GitHub pull requests. A number of parallel builds test a variety of
 compiler and build configurations as defined above.
@@ -160,7 +160,7 @@ a shared pointer to the HPMC integrator to access this information.
 There are two MD integrators: `IntegratorTwoStep` implements normal MD simulations and
 `FIREENergyMinimizer` implements energy minimization. In MD, the integrator maintains the list of
 user-supplied forces (`ForceCompute`) to apply to particles. Both integrators also maintain a list
-of user-supplied integration methos (`IntegrationMethodTwoStep`). Each method instance operates
+of user-supplied integration methods (`IntegrationMethodTwoStep`). Each method instance operates
 on a single particle group (`ParticleGroup`) and is solely responsible for integrating the equations
 of motion of all particles in that group.
 
@@ -195,19 +195,19 @@ even when the use of that code is used only in host code. To work around these c
 kernels in HOOMD-blue are called via minimal driver functions. These driver functions are not member
 functions of their respective class, and therefore must take a long C-style argument list consisting
 of bare pointers to data arrays, array sizes, etc... The ABI for these calls is not strictly C, as
-driver functions may be templated on functor classes and/or accept lightwight C++ objects as
+driver functions may be templated on functor classes and/or accept lightweight C++ objects as
 parameters (such as `BoxDim`).
 
 ## Autotuning
 
 HOOMD-blue automatically tunes kernel block sizes, threads per particle, and other kernel launch
-paramters. The `Autotuner` class manages the sparse multi-dimensional of parameters for each kernel.
+parameters. The `Autotuner` class manages the sparse multidimensional of parameters for each kernel.
 It dynamically cycles through the possible parameters and records the performance of each using CUDA
 events. After scanning through all parameters, it selects the best performing one to continue
 executing. GPU code in HOOMD-blue should instantiate and use one `Autotuner` for each kernel.
 Classes that use have `Autotuner` member variables should inherit from `Autotuned` which tracks all
 the autotuners and provides a UI to users. When needed, classes should override the base class
-`isAutotuningComplete` and `startAutotuning` as to pass the calls on to child objects. not otherwise
+`isAutotuningComplete` and `startAutotuning` as to pass the calls on to child objects not otherwise
 managed by the `Simulation`. For example, `PotentialPair::isAutotuningComplete`, calls both
 `ForceCompute::isAutotuningComplete` and `m_nlist->isAutotuningComplete` and combines the results.
 
@@ -300,13 +300,13 @@ specification defining the validation logic for its keys. `ParameterDict`
 contains logic when given a pybind11 produced Python object can sync between C++
 and Python. See `ParameterDict.__setitem__` for this logic. Attribute specific
 logic can be created using the `_getters` and `_setters` attributes. The logic
-requires (outside custom getters and setters that all `ParameterDict` keys be
+requires (outside custom getters and setters) that all `ParameterDict` keys be
 available as properties of the C++ object using the pybind11 property
 implementation
 (https://pybind11.readthedocs.io/en/stable/classes.html#instance-and-static-fields).
 Properties can be read-only which means they will never be set through
 `ParameterDict`, but can be through the C++ class constructor. Attempting to set
-such a property after attaching will result in an `MutabilityError` being thrown.
+such a property after attaching will result in a `MutabilityError` being thrown.
 
 This class should be used to define all attributes shared with C++ member
 variables that are on a per-object basis (i.e. not per type). Examples of
@@ -399,18 +399,18 @@ written in Python. See the examples in `hoomd/write/table.py` and
 
 ### Pickling
 
-By default all Python subclasses of `hoomd.operation._HOOMDBaseObject` support
+By default, all Python subclasses of `hoomd.operation._HOOMDBaseObject` support
 pickling. This is to facilitate restartability and reproducibility of
 simulations. For understanding what *pickling* and Python's supported magic
-methods regarding it are see https://docs.python.org/3/library/pickle.html. In
-general we prefer using `__getstate__` and `__setstate__` if possible to make
+methods regarding it see https://docs.python.org/3/library/pickle.html. In
+general, we prefer using `__getstate__` and `__setstate__` if possible to make
 class's picklable.  For the implementation of the default pickling support for
 `hoomd.operation._HOOMDBaseObject` see the class's `__getstate__` method.
 *Notice* that we do not implement a generic `__setstate__`. We rely on Python's
 default generally which is somewhat equivalent to `self.__dict__ =
 self.__getstate__()`. Adding a custom `__setstate__` method is fine if necessary
 (see [hoomd/write/table.py](hoomd/write/table.py)).  However, using `__reduce__`
-is an appropriate alternative if is significantly reduces code complexity or has
+is an appropriate alternative if significantly reduces code complexity or has
 demonstrable advantages; see [hoomd/filter/set\_.py](hoomd/filter/set_.py) for
 an example of this approach.  _Note_ that `__reduce__` requires that a function
 be able to fully recreate the current state of the object (this means that often
@@ -436,7 +436,7 @@ wrappers, supporting pickling using pybind11 (see
 https://pybind11.readthedocs.io/en/stable/advanced/classes.html#pickling-support)
 is acceptable as well. Care just needs to be made that users are not exposed to
 C++ classes that "slip" out of their Python subclasses which can happen if no
-reference in Python remains to a unpickled object. See
+reference in Python remains to an unpickled object. See
 [hoomd/Trigger.cc](hoomd/Trigger.cc) for examples of using pybind11.
 
 **Supporting Class Changes**
@@ -457,7 +457,7 @@ internal attributes should not cause problems as well.
 
 HOOMD allows for C++ classes to expose their GPU and CPU data buffers directly
 in Python using the `__cuda_array_interface__` and `__array_interface__`. This
-behavior is controlled using the `hoomd.data.local_access._LocalAcces` class in
+behavior is controlled using the `hoomd.data.local_access._LocalAccess` class in
 Python and the classes found in `hoomd/PythonLocalDataAccess.h`. See these files
 for more details. For example implementations look at `hoomd/ParticleData.h`.
 
@@ -475,12 +475,48 @@ The top level directories are:
 
 ## User
 
-The user facing documentation is compiled into a human readable document by Sphinx. The
+The user facing documentation is compiled into a human-readable document by Sphinx. The
 documentation consists of `.rst` files in the `sphinx-doc` directory and the docstrings of
 user-facing Python classes in the implementation (imported by the Sphinx autodoc extension).
 HOOMD-blue's Sphinx configuration defines mocked imports so that the documentation may be built from
-the source directory without needing to compile the C++ source code. This is greatly beneficial when
-building the documentation on readthedocs.
+the source directory without needing to compile the C++ source code.
+
+`autodoc` defaults to one HTML page per module. Users find it more convenient to read
+documentation with one page per class. The file `sphinx-doc/generate-toctree.py`
+imports `hoomd`, reads the `__all__` member and then recursively generates `.rst` files
+for each module and class. `generate-toctree.py` is run as a `pre-commit` hook to ensure
+that the documentation is always updated.
+
+Users also strongly prefer not to navigate up the super class chain in the documentation
+in order to discover the members of a given class. Unfortunately, we are not able to
+use Sphinx'x automatic inherit-documentation because HOOMD extensively uses
+`__getattr__/__setattr__`. To meet this need, HOOMD based classes define a class-level
+`_doc_inherited` string that summarizes the inherited members. Classes should append
+this string to `__doc__` and _then_ add their inherited members (if any) to
+`_doc_inherited`.
+
+Sybil parses only docstrings, so there can be no Sybil codeblock examples in
+`_doc_inherited`. At the same time, Sphinx always adds autodoc members **after** the
+docstring contents. To work around this and provide documentation in a consistent and
+meaningful order: class docstrints should include the text `{inherited}` and update the
+docstring with `__doc__ = __doc__.replace("{inherited}", Parent._doc_inherited)`.
+
+After `{inherited}`, the docstring should include the lines
+```
+----------
+
+**Members defined in** `ThisClassName`:
+```
+Similarly, any additions to `_doc_inherited` should start with
+```
+----------
+
+**Members inherited from** `ThisClassName <hoomd.module.ThisClassName>:`
+```
+Together, these visually break up the sections and allow the user to see which
+methods come from where. Each entry in `_doc_inherited` should repeat only the brief
+description and provide a link to the full description (follow
+the examples in the codebase when writing your own).
 
 The tutorial portion of the documentation is written in Jupyter notebooks housed in the
 [hoomd-examples][hoomd_examples] repository. HOOMD-blue includes these in the generated Sphinx

CHANGELOG.rst

@@ -1,6 +1,3 @@
-.. Copyright (c) 2009-2024 The Regents of the University of Michigan.
-.. Part of HOOMD-blue, released under the BSD 3-Clause License.
-
 Change Log
 ==========
 
@@ -43,6 +40,8 @@ Change Log
 * ``hoomd.hpmc.external.field.Harmonic`` is now ``hoomd.hpmc.external.Harmonic`` and works
   with ``IntegratorHPMC.external_potentials``
   (`#1941 <https://github.com/glotzerlab/hoomd-blue/pull/1941>`__).
+* Document one class per html page and show inherited members in class documentation
+  (`#1952 <https://github.com/glotzerlab/hoomd-blue/pull/1952>`__).
 
 *Removed*
 
@@ -266,7 +265,7 @@ Change Log
 * ``hoomd.variant.box.InverseVolumeRamp`` - Linearly ramp the inverse volume of the system
   (`#1685 <https://github.com/glotzerlab/hoomd-blue/pull/1685>`__).
 * ``hoomd.hpmc.update.QuickCompress`` now accepts a ``hoomd.variant.box.BoxVariant`` object for
-  `target_box` (`#1736 <https://github.com/glotzerlab/hoomd-blue/pull/1736>`__).
+  ``target_box`` (`#1736 <https://github.com/glotzerlab/hoomd-blue/pull/1736>`__).
 * ``box`` argument to ``hoomd.update.BoxResize`` that accepts a ``hoomd.variant.box.BoxVariant``
   (`#1740 <https://github.com/glotzerlab/hoomd-blue/pull/1740>`__).
 * ``hoomd.hpmc.pair.Union`` computes pair potentials between unions of points. Replaces

CONTRIBUTING.rst

@@ -88,15 +88,9 @@ User documentation
 Write user documentation
 ________________________
 
-Document public-facing API with Python docstrings in Google style.
-
-Document version status
-_______________________
-
-Add `versionadded, versionchanged, and deprecated Sphinx directives
-<https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionadded>`__
-to each user-facing Python class, method, etc., so that users will be aware of how functionality
-changes from version to version. Remove this when breaking APIs in major releases.
+Document public-facing API with Python docstrings in Google style, use the ``_doc_inherited``
+member as documented in ``ARCHITECTURE.md`` and list new public classes and functions in
+``__all__``.
 
 Add developer to the credits
 ____________________________

hoomd/__init__.py

@@ -28,7 +28,7 @@
 * `hoomd.md` - Molecular dynamics.
 
 See Also:
-    Tutorial: :doc:`tutorial/00-Introducing-HOOMD-blue/00-index`
+    Tutorial: :doc:`/tutorial/00-Introducing-HOOMD-blue/00-index`
 
 .. rubric:: Signal handling
 
@@ -42,6 +42,8 @@
 import os
 import signal
 
+__all__ = []
+
 # Work around /usr/lib64/slurm/auth_munge.so: undefined symbol: slurm_conf
 # error on Purdue Anvil.
 if os.environ.get('RCAC_CLUSTER') == 'anvil':
@@ -64,7 +66,8 @@
 
 from hoomd import version
 from hoomd import trigger
-from hoomd.box import Box, box_like
+from hoomd import box
+from hoomd.box import Box
 from hoomd import variant
 from hoomd import data
 from hoomd import filter
@@ -74,6 +77,8 @@
 from hoomd import update
 from hoomd import communicator
 from hoomd import util
+from hoomd import operation
+
 from hoomd import write
 from hoomd import wall
 from hoomd import _hoomd
@@ -115,3 +120,32 @@ def _hoomd_sys_excepthook(type, value, traceback):
     signal.signal(signal.SIGTERM, lambda n, f: sys.exit(1))
 except ValueError:
     pass
+
+__all__ = [
+    'version',
+    'trigger',
+    'box',
+    'Box',
+    'variant',
+    'data',
+    'filter',
+    'device',
+    'error',
+    'mesh',
+    'update',
+    'communicator',
+    'util',
+    'operation',
+    'write',
+    'wall',
+    'tune',
+    'logging',
+    'custom',
+    'hpmc',
+    'md',
+    'mpcd',
+    'Simulation',
+    'State',
+    'Operations',
+    'Snapshot',
+]