Fix all sphinx warnings (#1796)

Yoshanuikabundi · j-wags · web-flow · commit 5ffcb58714c9 · 2024-02-07T09:52:55.000-08:00
* Fix Sphinx warnings and fail on warning

* Fix remaining Sphinx warnings by translating release history to markdown

* Update changelog

* fix weird formatting thing in releasehistory

* fix unclosed literal in to_qcschema docstring

---------

Co-authored-by: Jeff Wagner &lt;jeffrey.wagner+github@openforcefield.org&gt;
Co-authored-by: Jeff Wagner &lt;jwagnerjpl@gmail.com&gt;
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -2,6 +2,7 @@
 version: 2
 sphinx:
   configuration: docs/conf.py
+  fail_on_warning: true
 build:
   os: ubuntu-20.04
   tools:
diff --git a/FAQ.md b/FAQ.md
@@ -66,10 +66,13 @@ This behavior is in line with OpenFF's general attitude of requiring users to ex
 
 ## I'm having troubles installing the OpenFF Toolkit on my Apple Silicon Mac.
 
-As of August 2022, some upstreams (at least AmberTools, possibly more) are not built on `osx-arm64`, so installing the OpenFF stack is only possible with [Rosetta](https://support.apple.com/en-au/HT211861). See the [platform support](installation/m1) section of the installation documentation for more.
+As of August 2022, some upstreams (at least AmberTools, possibly more) are not built on `osx-arm64`, so installing the OpenFF stack is only possible with [Rosetta]. See the [platform support] section of the installation documentation for more.
 
 (Keywords `osx-arm64`, M1 Mac, M2 Mac)
 
+[Rosetta]: https://support.apple.com/en-au/HT211861
+[platform support]: inv:#install_arm
+
 ## My mamba/conda installation of the toolkit doesn't appear to work. What should I try next?
 
 We recommend that you install the toolkit in a fresh environment, explicitly passing the channels to be used, in-order:
diff --git a/docs/environment.yml b/docs/environment.yml
@@ -7,11 +7,11 @@ channels:
 dependencies:
     - pip
     # readthedocs dependencies
-    - myst-nb
-    - myst-parser>=0.14
+    - myst-nb=1
+    - myst-parser
     - docutils
     - sphinx-notfound-page
-    - sphinx>=5.0,<6
+    - sphinx=6
     # conda build dependencies
     - python=3.9
     - setuptools
diff --git a/docs/installation.md b/docs/installation.md
@@ -26,7 +26,7 @@ If you do not have Mamba or Conda installed, see the [ecosystem installation doc
 Installation via the Mamba package manager is the recommended method since all dependencies are automatically fetched and installed for you.
 :::
 
-[ecosystem installation documentation]: openff.docs:install
+[ecosystem installation documentation]: inv:openff.docs#install
 
 (installation/platforms)=
 
diff --git a/docs/releasehistory.md b/docs/releasehistory.md
diff --git a/docs/topology.md b/docs/topology.md
@@ -11,7 +11,7 @@ including offering serialization to a variety of standard formats (including [XM
 
 ## Primary objects
 
-:::{eval-rst}
+```{eval-rst}
 .. currentmodule:: openff.toolkit.topology
 .. autosummary::
     :nosignatures:
@@ -20,11 +20,11 @@ including offering serialization to a variety of standard formats (including [XM
     FrozenMolecule
     Molecule
     Topology
-:::
+```
 
 ## Secondary objects
 
-:::{eval-rst}
+```{eval-rst}
 .. currentmodule:: openff.toolkit.topology
 .. autosummary::
     :nosignatures:
@@ -37,5 +37,5 @@ including offering serialization to a variety of standard formats (including [XM
     ImproperDict
     HierarchyScheme
     HierarchyElement
-:::
+```
 
diff --git a/docs/users/concepts.md b/docs/users/concepts.md
@@ -21,6 +21,6 @@ OpenFF [`ForceField`](openff.toolkit.typing.engines.smirnoff.forcefield.ForceFie
 : An object generated from an OFFXML file (or other source of SMIRNOFF data).
   Most information from the SMIRNOFF data source is stored in this object's several `ParameterHandler`s, however some top-level SMIRNOFF data is stored in the `ForceField` object itself.
 
-OpenFF [`Interchange`](openff.interchange:index)
+OpenFF [`Interchange`](inv:openff.interchange#index)
 : A `Topology` that has been parametrized by a `ForceField`. An `Interchange` contains all the information needed to calculate an energy or start a simulation. `Interchange` also provides methods to export this information
 to MD simulation engines.
diff --git a/docs/users/developing.md b/docs/users/developing.md
@@ -398,7 +398,7 @@ Some CI builds run using only RDKit as a backend, some run using only OpenEye To
 
 The CI matrix is currently as follows:
 
-:::{eval-rst}
+```{eval-rst}
 +-----------------------+------------+-----------+-------------+------------+-----------+-------------+
 |                       | Linux                                | macOS                                |
 +-----------------------+------------+-----------+-------------+------------+-----------+-------------+
@@ -414,4 +414,4 @@ The CI matrix is currently as follows:
 +-----------------------+------------+-----------+-------------+------------+-----------+-------------+
 | Python 3.12 and newer | Pending official releases and upstream support                              | 
 +-----------------------+------------+-----------+-------------+------------+-----------+-------------+
-:::
+```
diff --git a/docs/users/smirnoff.md b/docs/users/smirnoff.md
@@ -84,7 +84,7 @@ general or as specific as needed.
 [SMIRKS]: https://www.daylight.com/dayhtml/doc/theory/theory.smirks.html
 [standards repository]: https://openforcefield.github.io/standards/standards/smirnoff/
 [`Interchange`]: openff.interchange.Interchange
-[producing input files and data]: openff.interchange:using/output
+[producing input files and data]: inv:openff.interchange#using/output
 
 :::{hint} 
 This page is not the SMIRNOFF spec; it has been moved to the
diff --git a/openff/toolkit/topology/molecule.py b/openff/toolkit/topology/molecule.py
@@ -4416,7 +4416,7 @@ def to_qcschema(self, multiplicity=1, conformer=0, extras=None):
 
         The kekule structure of the molecule is saved in two places on the returned Molecule:
 
-        * ``extras["canonical_isomeric_explicit_hydrogen_mapped_smiles"]
+        * ``extras["canonical_isomeric_explicit_hydrogen_mapped_smiles"]``
         * ``identifiers["canonical_isomeric_explicit_hydrogen_mapped_smiles"]``
 
         .. warning :: This API is experimental and subject to change.
diff --git a/openff/toolkit/topology/topology.py b/openff/toolkit/topology/topology.py
@@ -1567,7 +1567,7 @@ def from_pdb(
         All molecules in the PDB file have the following requirements:
 
         * Polymer molecules must use the standard atom names described in the
-          `PDB Chemical Component dictionary <https://www.wwpdb.org/data/ccd>`_
+          `PDB Chemical Component Dictionary <https://www.wwpdb.org/data/ccd>`_
           (PDB CCD).
         * There must be no missing atoms (all hydrogens must be explicit).
         * All particles must correspond to an atomic nucleus (particles in the
@@ -1669,13 +1669,15 @@ def from_pdb(
          HierarchyElement ('B', '2', ' ', 'CYS') of iterator 'residues' containing 11 atom(s),
          HierarchyElement ('B', '3', ' ', 'NME') of iterator 'residues' containing 6 atom(s)]
 
-         Polymer systems can also be supported if _custom_substructures are given as a dict[str, list[str]],
-         where the keys are unique atom names and the values are lists of substructure smarts. The
-         substructure smarts must follow the same format as given in
-         "proteins/aa_residues_substructures_explicit_bond_orders_with_caps_explicit_connectivity.json":
-         ”<bond>[#<atomic number>D<degree>+<formal charge>:<id>]<bond>” for monomer atoms and
-         ”<bond>[*:<id>]” for adjacent neighboring atoms
-         (NOTE: This functionality is experimental!)
+        Polymer systems can also be supported if ``_custom_substructures`` are
+        given as a ``dict[str, list[str]]``, where the keys are unique atom
+        names and the values are lists of substructure SMARTS. The substructure
+        SMARTS must follow the same format as given in the `residue
+        substructure connectivity library
+        <https://github.com/openforcefield/openff-toolkit/blob/main/openff/toolkit/data/proteins/aa_residues_substructures_explicit_bond_orders_with_caps_explicit_connectivity.json>`_:
+        ``"<bond>[#<atomic number>D<degree>+<formal charge>:<id>]<bond>"`` for monomer
+        atoms and ``"<bond>[*:<id>]"`` for adjacent neighboring atoms
+        (NOTE: This functionality is experimental!)
 
         >>> PE_substructs = {
         ...     "PE": [
diff --git a/openff/toolkit/typing/engines/smirnoff/forcefield.py b/openff/toolkit/typing/engines/smirnoff/forcefield.py
@@ -1239,6 +1239,15 @@ def label_molecules(self, topology):
         For each molecule, a dictionary of force types is returned, and for each force type,
         each force term is provided with the atoms involved, the parameter id assigned, and the corresponding SMIRKS.
 
+        .. todo::
+           What is the most useful API for this method?
+
+           - Should we instead accept :class:`Molecule` objects as input and
+             individually return labels?
+           - Should we attach the labels to the :class:`Molecule` object?
+           - Or should we label all interactions in a :class:`Topology` instead
+             of just labeling its ``unique_molecules``?
+
         Parameters
         ----------
         topology : openff.toolkit.topology.Topology
@@ -1253,16 +1262,6 @@ def label_molecules(self, topology):
             ['HarmonicBondForce']`` gives details for the harmonic bond
             parameters for the first molecule. Each element is a list of the
             form: ``[ ( [ atom1, ..., atomN], parameter_id, SMIRKS), ... ]``.
-
-
-        .. todo::
-           What is the most useful API for this method?
-           - Should we instead accept :class:`Molecule` objects as input and
-             individually return labels?
-           - Should we attach the labels to the :class:`Molecule` object?
-           - Or should we label all interactions in a :class:`Topology` instead
-             of just labeling its ``unique_molecules``?
-
         """
         from openff.toolkit import Topology
         from openff.toolkit.typing.engines.smirnoff.parameters import VirtualSiteHandler
diff --git a/openff/toolkit/typing/engines/smirnoff/parameters.py b/openff/toolkit/typing/engines/smirnoff/parameters.py
@@ -94,6 +94,21 @@
 _cal_mol_a2 = unit.calorie / unit.mole / unit.angstrom**2
 
 
+# Hack to make Sphinx happy without breaking changes
+class _UNDEFINED:
+    """
+    Marker type for an undeclared default parameter.
+
+    Custom type used by ``ParameterAttribute`` to differentiate between ``None``
+    and undeclared default.
+    """
+
+    pass
+
+
+UNDEFINED = _UNDEFINED
+
+
 def _linear_inter_or_extrapolate(points_dict, x_query):
     """
     Linearly interpolate or extrapolate based on a piecewise linear function
@@ -320,10 +335,8 @@ class ParameterAttribute:
 
     """
 
-    class UNDEFINED:
-        """Custom type used by ``ParameterAttribute`` to differentiate between ``None`` and undeclared default."""
-
-        pass
+    UNDEFINED = UNDEFINED
+    """Marker type for an undeclared default parameter."""
 
     def __init__(
         self,
