Merge pull request #1079 from openforcefield/update-sphinx

Update Sphinx to 6.1.2

Author: mattwthompson

devtools/conda-envs/docs_env.yaml

@@ -20,8 +20,8 @@ dependencies:
   - myst-parser
   - numpydoc
   - autodoc-pydantic =2
-  - sphinx ~=4.4
+  - sphinx ==6.1.3
   - sphinxcontrib-mermaid
   - sphinx-notfound-page
   - pip:
-    - git+https://github.com/openforcefield/openff-sphinx-theme.git@main
+      - git+https://github.com/openforcefield/openff-sphinx-theme.git@main

docs/conf.py

@@ -102,7 +102,7 @@
 autodoc_default_options = {
     "member-order": "bysource",
     "undoc-members": True,
-    "inherited-members": [],
+    "inherited-members": "",
     "show-inheritance": True,
 }
 autodoc_preserve_defaults = True
@@ -169,7 +169,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

docs/docutils.conf

@@ -0,0 +1,2 @@
+[html writers]
+table-style: colwidths-grid

docs/installation.md

@@ -1,6 +1,6 @@
 # Installation
 
-These instructions assume that the `mamba` package manager is installed. If you do not have Conda/Mamba or a drop-in replacement installed, see the [OpenFF installation documentation](openff.docs:install).
+These instructions assume that the `mamba` package manager is installed. If you do not have Conda/Mamba or a drop-in replacement installed, see the [OpenFF installation documentation](inv:openff.docs#install).
 
 ## Quick Installation
 

docs/using/plugins.md

@@ -8,7 +8,7 @@ Currently, systems using custom interactions can only be exported to OpenMM. The
 
 [`ParameterHandler`]: openff.toolkit.typing.engines.smirnoff.parameters.ParameterHandler
 [`SMIRNOFFCollection`]: openff.interchange.plugins.SMIRNOFFCollection
-[SetupTools entry points]: setuptools:userguide/entry_point
+[SetupTools entry points]: inv:setuptools#userguide/entry_point
 [`openmm.Force`]: openmm.openmm.Force
 
 ## Creating a custom `ParameterHandler`
@@ -46,9 +46,9 @@ The high-level objectives of a parameter handler are to:
   * define optional attributes such as `id`
 
 [`ParameterType`]: openff.toolkit.typing.engines.smirnoff.parameters.ParameterType
-[entry point group]: setuptools:userguide/entry_point
+[entry point group]: inv:setuptools#userguide/entry_point
 [`check_handler_compatibility`]: openff.toolkit.typing.engines.smirnoff.parameters.ParameterHandler.check_handler_compatibility
-[Toolkit documentation]: openff.toolkit:developing
+[Toolkit documentation]: inv:openff.toolkit#developing
 
 ## Creating a custom `SMIRNOFFCollection`
 

openff/interchange/components/interchange.py

@@ -120,12 +120,14 @@ def from_smirnoff(
 
         Notes
         -----
-        If the `Molecule` objects in the `topology` argument each contain conformers, the returned `Interchange` object
-        will have its positions set via concatenating the 0th conformer of each `Molecule`.
+        If the ``Molecule`` objects in the ``topology`` argument each contain
+        conformers, the returned ``Interchange`` object will have its positions
+        set via concatenating the 0th conformer of each ``Molecule``.
 
-        If the `Molecule` objects in the `topology` argument have stored partial charges, these are ignored and charges
-        are assigned according to the contents of the force field. To override the force field and use preset charges,
-        use the `charge_from_molecules` argument.
+        If the ``Molecule`` objects in the ``topology`` argument have stored
+        partial charges, these are ignored and charges are assigned according to
+        the contents of the force field. To override the force field and use
+        preset charges, use the ``charge_from_molecules`` argument.
 
         Examples
         --------
@@ -342,7 +344,7 @@ def to_gromacs(
         Molecule names in written files are not guaranteed to match the `Moleclue.name` attribute of the
         molecules in the topology, especially if they are empty strings or not unique.
 
-        See `to_gro` and `to_top` for more details.
+        See :py:meth:`to_gro <Interchange.to_gro>` and :py:meth:`to_top <Interchange.to_top>` for more details.
 
         """
         from openff.interchange.interop.gromacs.export._export import GROMACSWriter
@@ -430,6 +432,9 @@ def to_gro(self, file_path: Path | str, decimal: int = 3):
         decimal: int, default=3
             The number of decimal places to use when writing the GROMACS coordinate file.
 
+        Notes
+        -----
+
         Residue IDs must be positive integers (or string representations thereof).
 
         Residue IDs greater than 99,999 are reduced modulo 100,000 in line with common GROMACS practice.
@@ -569,9 +574,10 @@ def to_openmm_topology(
         Parameters
         ----------
         collate
-            If False, the default, all virtual sites will be added to a single residue at the end of the topology.
-            If True, virtual sites will be collated with their associated molecule and added to the residue of the last
-            atom in the molecule they belong to.
+            If ``False``, the default, all virtual sites will be added to a
+            single residue at the end of the topology. If ``True``, virtual
+            sites will be collated with their associated molecule and added to
+            the residue of the last atom in the molecule they belong to.
 
         """
         from openff.interchange.interop.openmm._topology import to_openmm_topology
@@ -593,9 +599,14 @@ def to_openmm_simulation(
         **kwargs,
     ) -> "openmm.app.simulation.Simulation":
         """
-        Export this Interchange to an OpenMM `Simulation` object.
+        Export this Interchange to an OpenMM ``Simulation`` object.
+
+        A :py:class:`Simulation <openmm.app.simulation.Simulation>` encapsulates
+        all the information needed for a typical OpenMM simulation into a single
+        object with a simple API.
 
-        Positions are set on the `Simulation` if present on the `Interchange`.
+        Positions are set on the ``Simulation`` if present on the
+        ``Interchange``.
 
         Additional forces, such as a barostat, should be added with the
         ``additional_forces`` argument to avoid having to re-initialize