docs: api-ref (#8)

docs/api/_static/style.css

@@ -0,0 +1,3 @@
+.wy-nav-content {
+    max-width: none;
+}

docs/api/conf.py

@@ -29,6 +29,8 @@
     "sphinx.ext.viewcode",
     "sphinx_autodoc_typehints",
     "sphinxcontrib.autodoc_pydantic",
+    "sphinx_toolbox.more_autodoc.typevars",
+    "sphinx_paramlinks",
 ]
 
 templates_path = ["_templates"]
@@ -45,17 +47,28 @@
 # -- Options for autodoc --------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration
 
+autodoc_typehints = "signature"
 autodoc_member_order = "groupwise"
+autodoc_default_options = {
+    "autoclass_content": "class",
+    "show-inheritance": True,
+}
 
 # -- Options for pydantic_autodoc --------------------------------------------
 # https://autodoc-pydantic.readthedocs.io/en/stable/users/configuration.html
 
 autodoc_pydantic_model_show_json = False
+autodoc_pydantic_field_list_validators = False
 autodoc_pydantic_model_member_order = "groupwise"
 autodoc_pydantic_model_show_field_summary = False
 autodoc_pydantic_model_show_config_summary = False
 autodoc_pydantic_model_show_validator_summary = False
 
+# -- Options for sphinx-paramlinks -------------------------------------------
+# https://github.com/sqlalchemyorg/sphinx-paramlinks
+
+paramlinks_hyperlink_param = "name_and_symbol"
+
 # -- Event handlers ----------------------------------------------------------
 
 
@@ -77,4 +90,5 @@ def skip_member_handler(app, objtype, membername, member, skip, options):  # noq
 
 
 def setup(app):
+    app.add_css_file("my_theme.css")
     app.connect("autodoc-skip-member", skip_member_handler)

docs/api/rst/artschema/framework.rst

@@ -2,6 +2,18 @@
 Framework
 =========
 
+.. autotypevar:: mlopus.artschema.framework.A
+   :no-value:
+   :no-type:
+
+.. autotypevar:: mlopus.artschema.framework.D
+   :no-value:
+   :no-type:
+
+.. autotypevar:: mlopus.artschema.framework.L
+   :no-value:
+   :no-type:
+
 .. autopydantic_model:: mlopus.artschema.Dumper
    :private-members: _dump, _verify
 

docs/api/rst/artschema/index.rst

@@ -5,14 +5,10 @@ Artifact Schemas
 .. automodule:: mlopus.artschema
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Contents:
 
    framework
-
-.. toctree::
-   :maxdepth: 1
-
    tags
    helpers
    specs

docs/api/rst/artschema/specs.rst

@@ -4,12 +4,16 @@ Specs & Catalog
 
 .. automodule:: mlopus.artschema.specs
 
+.. autopydantic_model:: mlopus.artschema.RunArtifact
+   :exclude-members: cache, export, load, log, apply_defaults
+
+.. autopydantic_model:: mlopus.artschema.ModelVersionArtifact
+   :exclude-members: cache, export, load, log, apply_defaults
+
 .. autopydantic_model:: mlopus.artschema.LogArtifactSpec
    :exclude-members: with_defaults
-   :show-inheritance:
 
 .. autopydantic_model:: mlopus.artschema.LoadArtifactSpec
    :exclude-members: with_defaults
-   :show-inheritance:
 
 .. autopydantic_model:: mlopus.artschema.ArtifactsCatalog

docs/api/rst/artschema/tags.rst

@@ -3,6 +3,7 @@ Tags
 ====
 
 .. autopydantic_model:: mlopus.artschema.Tags
+   :exclude-members: get_schema
 
 .. autopydantic_model:: mlopus.artschema.ClassSpec
    :exclude-members: parse_class

docs/api/rst/mlflow/traits.rst

@@ -7,4 +7,3 @@ Traits
 .. autopydantic_model:: mlopus.mlflow.MlflowRunMixin
 
 .. autopydantic_model:: mlopus.mlflow.MlflowRunManager
-   :show-inheritance:

docs/api/rst/mlflow/utils.rst

@@ -3,5 +3,5 @@ Utilities
 =========
 
 .. autofunction:: mlopus.mlflow.list_api_plugins
-.. autofunction:: mlopus.mlflow.api_conf_schema
 .. autofunction:: mlopus.mlflow.get_api
+.. autofunction:: mlopus.mlflow.api_conf_schema

pyproject.toml

@@ -59,9 +59,11 @@ dev-dependencies = [
     "sphinx                    <7",
     "autodoc-pydantic          <2",
     "sphinx-rtd-theme          ~=2.0",
+    "sphinx-paramlinks         ~=0.6",
     "enum-tools[sphinx]        ~=0.12",
     "sphinx-code-include       ~=1.4",
     "sphinx-autodoc-typehints  ~=1.23",
+    "sphinx-toolbox>=3.8.0",
 ]
 
 # === Commitizen ==================================================================================
@@ -140,4 +142,4 @@ select = [
     "TID",
     "SIM",
 ]
-ignore = []
+ignore = ["E501"]

src/mlopus/artschema/__init__.py

@@ -2,17 +2,23 @@
 reusable dumpers/loaders for custom model/dataset classes.
 
 Schemas can be used standalone or registered in the tags of MLflow entities
-such as experiments, runs, models and model versions, which allows loading
-artifacts from these entities.
-
-Then, artifacts associated to those entities can be saved/loaded/verified
-just by providing the alias of a previously registered schema.
+such as experiments, runs, models and model versions. In the second case,
+artifacts associated to those entities can be saved/loaded/verified
+just by providing the alias of a registered schema.
 """
 
 from .catalog import ArtifactsCatalog
 from .framework import Dumper, Loader, Schema
 from .helpers import load_artifact, get_schema, log_model_version, log_run_artifact, get_schemas
-from .specs import parse_load_specs, LoadArtifactSpec, parse_logart_specs, LogArtifactSpec
+from .specs import (
+    parse_load_specs,
+    LoadArtifactSpec,
+    parse_logart_specs,
+    LogArtifactSpec,
+    RunArtifact,
+    ModelVersionArtifact,
+)
+
 from .tags import Tags, ClassSpec
 
 __all__ = [
@@ -31,4 +37,6 @@
     "parse_load_specs",
     "LogArtifactSpec",
     "parse_logart_specs",
+    "RunArtifact",
+    "ModelVersionArtifact",
 ]

src/mlopus/artschema/catalog.py

@@ -15,20 +15,33 @@ class ArtifactsCatalog(pydantic.BaseModel):
     Useful for type-safe loading/downloading/exporting
     artifacts based on parsed application settings.
 
+    Example settings:
+
+    .. code-block:: yaml
+
+        foo:
+            schema: package.module:Schema  # Schema specified explicitly by fully qualified class name
+            subject:
+                run_id: 12345678
+                path_in_run: foo
+        bar:
+            schema: default  # Schema obtained by alias from model version tags or parent model tags
+            subject:
+                model_name: foo
+                model_version: 3
+
     Example usage:
 
     .. code-block:: python
 
+        # Load the YAML settings above
+        artifact_specs: dict = ...
+
+        # Declare an artifact catalog
         class ArtifactsCatalog(mlopus.artschema.ArtifactsCatalog):
             foo: FooArtifact
             bar: BarArtifact
 
-        # Configure artifact sources
-        artifact_specs = {
-            "foo": {"subject": {"model_name": "foo", "model_version": "3"}},  # specs for a model artifact
-            "bar": {"subject": {"run_id": "1234567", "path_in_run": "bar"}},  # specs for a run artifact
-        }
-
         # Cache all artifacts and metadata and verify their files using the specified schemas
         ArtifactsCatalog.download(mlflow_api, artifact_specs)
 
@@ -37,6 +50,10 @@ class ArtifactsCatalog(mlopus.artschema.ArtifactsCatalog):
 
         artifacts_catalog.foo  # `FooArtifact`
         artifacts_catalog.bar  # `BarArtifact`
+
+    In the example above, `artifact_specs` is implicitly parsed into a mapping of `str` to :class:`LoadArtifactSpec`,
+    while the :attr:`~LoadArtifactSpec.subject` values of `foo` and `bar` are parsed into
+    :class:`~mlopus.artschema.RunArtifact` and :class:`~mlopus.artschema.ModelVersionArtifact`, respectively.
     """
 
     @classmethod
@@ -48,6 +65,9 @@ def load(
     ) -> "ArtifactsCatalog":
         """Load artifacts from specs using their respective schemas.
 
+        See also:
+            - :meth:`LoadArtifactSpec.load`
+
         :param mlflow_api:
         :param artifact_specs:
         """
@@ -63,9 +83,13 @@ def download(
     ) -> Dict[str, Path]:
         """Cache artifacts and metadata and verify the files against the schemas.
 
+        See also:
+            - :meth:`LoadArtifactSpec.download`
+
         :param mlflow_api:
         :param artifact_specs:
-        :param verify: Use schemas for verification after download.
+        :param verify: | Use schemas for verification after download.
+                       | See :meth:`~mlopus.artschema.Dumper.verify`.
         """
         paths = {}
 
@@ -87,10 +111,14 @@ def export(
     ) -> Dict[str, Path]:
         """Export artifacts and metadata caches while preserving cache structure.
 
+        See also:
+            - :meth:`LoadArtifactSpec.export`
+
         :param mlflow_api:
         :param artifact_specs:
         :param target: Cache export target path.
-        :param verify: Use schemas for verification after export.
+        :param verify: | Use schemas for verification after export.
+                       | See :meth:`~mlopus.artschema.Dumper.verify`.
         """
         paths = {}