use autosummary templates

docs/_templates/README.md

@@ -0,0 +1,5 @@
+# `templates` directory
+
+This directory is appended to the `templates_path` Sphinx config variable in `conf.py`. Jinja templates in this directory are available to Sphinx. This is used to provide an Autosummary template that supports an automatic API reference.
+
+Note that templates used for the *theme itself* are not placed in this directory! 

docs/_templates/autosummary/base.rst

@@ -0,0 +1,15 @@
+{% block title -%}
+
+{{ ("``" ~ objname ~ "``") | underline}}
+
+{%- endblock %}
+{% block base %}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ objname }}
+    {% if objtype in ["attribute", "data"] -%}
+    :no-value:
+    {%- endif %}
+
+{%- endblock %}

docs/_templates/autosummary/class.rst

@@ -0,0 +1,65 @@
+{% block title -%}
+
+.. raw:: html
+
+   <div style="display: None;">
+
+{{ ("``" ~ objname ~ "``") | underline('=')}}
+
+.. raw:: html
+
+   </div>
+
+{%- endblock %}
+{% block base %}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :member-order: alphabetical  {# For consistency with Autosummary #}
+   {% if show_inherited_members %}:inherited-members:
+   {% endif %}{% if show_undoc_members %}:undoc-members:
+   {% endif %}{% if show_inheritance %}:show-inheritance:
+   {% endif %}
+
+   {% block methods %}
+
+   {%- set doc_methods = [] -%}
+   {%- for item in methods -%}
+      {%- if item not in ["__new__", "__init__"] and (show_inherited_members or item not in inherited_members) -%}
+         {%- set _ = doc_methods.append(item) -%}
+      {%- endif -%}
+   {%- endfor %}
+
+   {% if doc_methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      :nosignatures:
+   {% for item in doc_methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+
+   {%- set doc_attributes = [] -%}
+   {%- for item in attributes -%}
+      {%- if show_inherited_members or item not in inherited_members -%}
+         {%- set _ = doc_attributes.append(item) -%}
+      {%- endif -%}
+   {%- endfor %}
+
+   {% if doc_attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+      :nosignatures:
+   {% for item in doc_attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+{% endblock %}

docs/_templates/autosummary/module.rst

@@ -0,0 +1,106 @@
+{% block title -%}
+
+{{ ("``" ~ objname ~ "``") | underline('=')}}
+
+{%- endblock %}
+{% block base %}
+
+.. automodule:: {{ fullname }}
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
+
+   {% block modules %}
+
+   {%- set included_modules = [] -%}
+   {%- for item in modules -%}
+      {%- if item not in exclude_modules -%}
+         {%- set _ = included_modules.append(item) -%}
+      {%- endif -%}
+   {%- endfor -%}
+
+   {% if included_modules %}
+   .. rubric:: Modules
+
+   .. autosummary::
+      :caption: Modules
+      :toctree:
+      :recursive:
+   {% for item in included_modules %}
+      ~{{ item }}
+   {%- endfor %}
+
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Module Attributes') }}
+
+   .. autosummary::
+      :caption: Attributes
+      :toctree:
+      :nosignatures:
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {%- endblock -%}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :caption: Functions
+      :toctree:
+      :nosignatures:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+
+   {%- set types = [] -%}
+   {%- for item in members -%}
+      {%- if not item.startswith('_') and not (
+         item in functions
+         or item in attributes
+         or item in exceptions
+         or fullname ~ "." ~ item in modules
+         or item in methods
+      ) -%}
+         {%- set _ = types.append(item) -%}
+      {%- endif -%}
+   {%- endfor %}
+
+   {% if types %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :caption: Classes
+      :toctree:
+      :nosignatures:
+   {% for item in types %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :caption: Exceptions
+      :toctree:
+      :nosignatures:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% endblock %}

docs/concepts/tokenizables.rst

@@ -238,9 +238,9 @@ Any nested ``GufeTokenizable``\s are left as-is.
         ChemicalSystem(name=phenol-solvent, components={'ligand': SmallMoleculeComponent(name=phenol), 'solvent': SolventComponent(name=O, K+, Cl-)})
         ],
     'edges': [
-        Transformation(stateA=ChemicalSystem(name=benzene-solvent, components={'ligand': SmallMoleculeComponent(name=benzene), 'solvent': SolventComponent(name=O, K+, Cl-)}), stateB=ChemicalSystem(name=toluene-solvent, components={'ligand': SmallMoleculeComponent(name=toluene), 'solvent': SolventComponent(name=O, K+, Cl-)}), protocol=<Protocol-d01baed9cf2500c393bd6ddb35ee38aa>, name=None),
-        Transformation(stateA=ChemicalSystem(name=benzene-solvent, components={'ligand': SmallMoleculeComponent(name=benzene), 'solvent': SolventComponent(name=O, K+, Cl-)}), stateB=ChemicalSystem(name=styrene-solvent, components={'ligand': SmallMoleculeComponent(name=styrene), 'solvent': SolventComponent(name=O, K+, Cl-)}), protocol=<Protocol-d01baed9cf2500c393bd6ddb35ee38aa>, name=None),
-        Transformation(stateA=ChemicalSystem(name=benzene-solvent, components={'ligand': SmallMoleculeComponent(name=benzene), 'solvent': SolventComponent(name=O, K+, Cl-)}), stateB=ChemicalSystem(name=phenol-solvent, components={'ligand': SmallMoleculeComponent(name=phenol), 'solvent': SolventComponent(name=O, K+, Cl-)}), protocol=<Protocol-d01baed9cf2500c393bd6ddb35ee38aa>, name=None)
+        Transformation(stateA=ChemicalSystem(name=benzene-solvent, components={'ligand': SmallMoleculeComponent(name=benzene), 'solvent': SolventComponent(name=O, K+, Cl-)}), stateB=ChemicalSystem(name=toluene-solvent, components={'ligand': SmallMoleculeComponent(name=toluene), 'solvent': SolventComponent(name=O, K+, Cl-)}), protocol=<Protocol-489fb1395a32c5183bcc1d43fa521960>, name=None),
+        Transformation(stateA=ChemicalSystem(name=benzene-solvent, components={'ligand': SmallMoleculeComponent(name=benzene), 'solvent': SolventComponent(name=O, K+, Cl-)}), stateB=ChemicalSystem(name=styrene-solvent, components={'ligand': SmallMoleculeComponent(name=styrene), 'solvent': SolventComponent(name=O, K+, Cl-)}), protocol=<Protocol-489fb1395a32c5183bcc1d43fa521960>, name=None),
+        Transformation(stateA=ChemicalSystem(name=benzene-solvent, components={'ligand': SmallMoleculeComponent(name=benzene), 'solvent': SolventComponent(name=O, K+, Cl-)}), stateB=ChemicalSystem(name=phenol-solvent, components={'ligand': SmallMoleculeComponent(name=phenol), 'solvent': SolventComponent(name=O, K+, Cl-)}), protocol=<Protocol-489fb1395a32c5183bcc1d43fa521960>, name=None)
         ],
     'name': None,
     '__qualname__': 'AlchemicalNetwork',
@@ -310,7 +310,7 @@ To show the structure of a keyed chain, below we have redacted all information e
     ('SmallMoleculeComponent-3b51f5f92521c712049da092ab061930', {...}),
     ('SmallMoleculeComponent-ec3c7a92771f8872dab1a9fc4911c795', {...}),
     ('SmallMoleculeComponent-8225dfb11f2e8157a3fcdcd673d3d40e', {...}),
-    ('Protocol-d01baed9cf2500c393bd6ddb35ee38aa', {...}),
+    ('Protocol-489fb1395a32c5183bcc1d43fa521960', {...}),
     ('ChemicalSystem-ba83a53f18700b3738680da051ff35f3', {
         'components': {
             'ligand': {':gufe-key:': 'SmallMoleculeComponent-3b51f5f92521c712049da092ab061930'},
@@ -332,12 +332,12 @@ To show the structure of a keyed chain, below we have redacted all information e
     ('Transformation-e8d1ccf53116e210d1ccbc3870007271', {
         'stateA': {':gufe-key:': 'ChemicalSystem-3c648332ff8dccc03a1e1a3d44bc9755'},
         'stateB': {':gufe-key:': 'ChemicalSystem-ba83a53f18700b3738680da051ff35f3'},
-        'protocol': {':gufe-key:': 'DummyProtocol-d01baed9cf2500c393bd6ddb35ee38aa'},
+        'protocol': {':gufe-key:': 'DummyProtocol-489fb1395a32c5183bcc1d43fa521960'},
         ...}),
     ('Transformation-4d0f802817071c8d14b37efd35187318', {
         'stateA': {':gufe-key:': 'ChemicalSystem-3c648332ff8dccc03a1e1a3d44bc9755'},
         'stateB': {':gufe-key:': 'ChemicalSystem-655f4d0008a537fe811b11a2dc4a029e'},
-        'protocol': {':gufe-key:': 'DummyProtocol-d01baed9cf2500c393bd6ddb35ee38aa'},
+        'protocol': {':gufe-key:': 'DummyProtocol-489fb1395a32c5183bcc1d43fa521960'},
         ...}),
     ('AlchemicalNetwork-f8bfd63bc848672aa52b081b4d68fadf', {
         'nodes': [

docs/conf.py

@@ -49,6 +49,9 @@
     "undoc-members": True,
 }
 
+# TODO: temporary workaround to get docs to build I figure out why only OpenMMSystemGeneratorFFSettings GufeQuantities won't serialize.
+autodoc_pydantic_model_show_json_error_strategy = "coerce"
+
 autosummary_generate = True
 
 intersphinx_mapping = {
@@ -68,7 +71,6 @@
     "rdkit",
 ]
 
-
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

docs/environment.yaml

@@ -3,7 +3,7 @@ channels:
 - https://conda.anaconda.org/jaimergp/label/unsupported-cudatoolkit-shim
 - https://conda.anaconda.org/conda-forge
 dependencies:
-- autodoc-pydantic
+- autodoc-pydantic >=2.0
 - openff-units
 - python=3.12
 - sphinx

environment.yml

@@ -13,7 +13,7 @@ dependencies:
   - pint
   - pip
   - pooch
-  - pydantic >1
+  - pydantic >=2.0
   - pytest
   - pytest-cov
   - pytest-xdist
@@ -25,4 +25,4 @@ dependencies:
   - sphinx-jsonschema==1.15
   - sphinx <7.1.2
   - pip:
-    - autodoc_pydantic<2.0.0
+    - autodoc_pydantic>=2.0.0

gufe/components/proteincomponent.py

@@ -56,8 +56,8 @@
 
 
 # ions and charges pulled from amber:
-# https://github.com/Amber-MD/AmberClassic/blob/42e88bf9a2214ba008140280713a430f3ecd4a90/dat/leap/lib/atomic_ions.lib#L1C1-L68C6
-ions_dict = {
+# see `amber list <https://github.com/Amber-MD/AmberClassic/blob/42e88bf9a2214ba008140280713a430f3ecd4a90/dat/leap/lib/atomic_ions.lib#L1C1-L68C6`_
+_ions_dict = {
     "AG": 1,
     "Ag": 2,
     "AL": 3,
@@ -268,15 +268,15 @@ def _from_openmmPDBFile(cls, openmm_PDBFile: PDBFile | PDBxFile, name: str = "")
         def _get_ion_charge(ion_key):
             ik = ion_key.strip()  # strip b/c we never want whitespace
 
-            if charge := ions_dict.get(ik):
+            if charge := _ions_dict.get(ik):
                 return charge
-            elif charge := ions_dict.get(ik.upper()):
+            elif charge := _ions_dict.get(ik.upper()):
                 return charge
-            elif charge := ions_dict.get(ik.strip(digits)):
+            elif charge := _ions_dict.get(ik.strip(digits)):
                 return charge
-            elif charge := ions_dict.get(ik.strip(digits).upper()):
+            elif charge := _ions_dict.get(ik.strip(digits).upper()):
                 return charge
-            elif charge := ions_dict.get(ik.strip(digits).title()):
+            elif charge := _ions_dict.get(ik.strip(digits).title()):
                 return charge
 
             # raise an error if we can't find a match

gufe/serialization/json.py

@@ -320,7 +320,7 @@ def is_legacy_path_dict(dct: dict) -> bool:
 
 SETTINGS_CODEC = JSONCodec(
     cls=SettingsBaseModel,
-    to_dict=lambda obj: {field: getattr(obj, field) for field in obj.__fields__},
+    to_dict=lambda obj: {field: getattr(obj, field) for field in obj.model_fields},
     from_dict=default_from_dict,
     is_my_dict=functools.partial(inherited_is_my_dict, cls=SettingsBaseModel),
 )

gufe/serialization/msgpack.py

@@ -68,7 +68,7 @@ def pack_default(obj) -> msgpack.ExtType:
             return msgpack.ExtType(MPEXT.NPGENERIC, npg_payload)
 
         case SettingsBaseModel():
-            settings_data = {field: getattr(obj, field) for field in obj.__fields__}
+            settings_data = {field: getattr(obj, field) for field in obj.model_fields}
             settings_data.update({"__class__": obj.__class__.__qualname__, "__module__": obj.__class__.__module__})
             settings_payload: bytes = msgpack.packb(settings_data, default=pack_default)
             return msgpack.ExtType(MPEXT.SETTINGS, settings_payload)