Merge pull request #1590 from jku/docs-tweaking

API doc improvements
theupdateframework · Oct 1, 2021 · d021331 · d021331
2 parents bb1ed9f + 4e83585
commit d021331
Show file tree

Hide file tree

Showing 18 changed files with 250 additions and 163 deletions.
diff --git a/docs/api/tuf.api.metadata.metadata.rst b/docs/api/tuf.api.metadata.metadata.rst
@@ -0,0 +1,4 @@
+Metadata class
+---------------------------------
+
+.. autoclass:: tuf.api.metadata.Metadata
diff --git a/docs/api/tuf.api.metadata.root.rst b/docs/api/tuf.api.metadata.root.rst
@@ -0,0 +1,4 @@
+Root class
+---------------------------------
+
+.. autoclass:: tuf.api.metadata.Root
diff --git a/docs/api/tuf.api.metadata.rst b/docs/api/tuf.api.metadata.rst
diff --git a/docs/api/tuf.api.metadata.snapshot.rst b/docs/api/tuf.api.metadata.snapshot.rst
@@ -0,0 +1,4 @@
+Snapshot class
+---------------------------------
+
+.. autoclass:: tuf.api.metadata.Snapshot
diff --git a/docs/api/tuf.api.metadata.supporting.rst b/docs/api/tuf.api.metadata.supporting.rst
@@ -0,0 +1,27 @@
+Supporting classes
+---------------------------------
+
+The Metadata API includes multiple classes that are used by the top-level
+ones (Root, Timestamp, Snapshot, Targets):
+
+.. autosummary::
+   :nosignatures:
+
+   tuf.api.metadata.DelegatedRole
+   tuf.api.metadata.Delegations
+   tuf.api.metadata.Key
+   tuf.api.metadata.MetaFile
+   tuf.api.metadata.Role
+   tuf.api.metadata.TargetFile
+
+.. autoclass:: tuf.api.metadata.DelegatedRole
+
+.. autoclass:: tuf.api.metadata.Delegations
+
+.. autoclass:: tuf.api.metadata.Key
+
+.. autoclass:: tuf.api.metadata.MetaFile
+
+.. autoclass:: tuf.api.metadata.Role
+
+.. autoclass:: tuf.api.metadata.TargetFile
diff --git a/docs/api/tuf.api.metadata.targets.rst b/docs/api/tuf.api.metadata.targets.rst
@@ -0,0 +1,4 @@
+Targets class
+---------------------------------
+
+.. autoclass:: tuf.api.metadata.Targets
diff --git a/docs/api/tuf.api.metadata.timestamp.rst b/docs/api/tuf.api.metadata.timestamp.rst
@@ -0,0 +1,4 @@
+Timestamp class
+---------------------------------
+
+.. autoclass:: tuf.api.metadata.Timestamp
diff --git a/docs/api/tuf.api.rst b/docs/api/tuf.api.rst
@@ -1,18 +1,19 @@
 Metadata API
 ===============
 
-The low-level Metadata API contains two modules:
+.. toctree::
 
-* :doc:`tuf.api.metadata` contains the actual Metadata abstraction
-  that higher level libraries and application code should use to interact
-  with TUF metadata. This abstraction provides safe reading and writing to
-  supported file formats and helper functions for accessing and modifying
-  the metadata contents.
-* :doc:`tuf.api.serialization` covers serializing the metadata into
-  specific wire formats (like json).
+   tuf.api.metadata.metadata
+   tuf.api.metadata.root
+   tuf.api.metadata.timestamp
+   tuf.api.metadata.snapshot
+   tuf.api.metadata.targets
 
 .. toctree::
    :hidden:
 
-   tuf.api.metadata
+   tuf.api.metadata.supporting
    tuf.api.serialization
+
+.. automodule:: tuf.api.metadata
+   :no-members:
diff --git a/docs/api/tuf.api.serialization.rst b/docs/api/tuf.api.serialization.rst
@@ -1,10 +1,10 @@
 Serialization
 =============================
 
+.. automodule:: tuf.api.serialization
+
 JSON serialization
 -----------------------------
 
 .. automodule:: tuf.api.serialization.json
-   :members:
-   :undoc-members:
    :show-inheritance:
diff --git a/docs/api/tuf.ngclient.config.rst b/docs/api/tuf.ngclient.config.rst
@@ -2,6 +2,4 @@ Configuration
 =============
 
 .. automodule:: tuf.ngclient.config
-   :members:
    :undoc-members:
-   :show-inheritance:
diff --git a/docs/api/tuf.ngclient.fetcher.rst b/docs/api/tuf.ngclient.fetcher.rst
@@ -2,6 +2,4 @@ Fetcher
 ============
 
 .. automodule:: tuf.ngclient.fetcher
-   :members:
    :undoc-members:
-   :show-inheritance:
diff --git a/docs/api/tuf.ngclient.updater.rst b/docs/api/tuf.ngclient.updater.rst
@@ -2,5 +2,3 @@ Updater
 =========
 
 .. automodule:: tuf.ngclient.updater
-   :members:
-   :special-members: __init__
diff --git a/docs/conf.py b/docs/conf.py
@@ -30,7 +30,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.napoleon']
+extensions = ['sphinx.ext.napoleon', 'sphinx.ext.autosummary']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -52,5 +52,19 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 #html_static_path = ['_static']
 
+# -- Autodoc configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
+
 autodoc_mock_imports = ['securesystemslib']
 
+# Tone down the "tuf.api.metadata." repetition
+add_module_names = False
+python_use_unqualified_type_names = True
+
+# Show typehints in argument doc lines, but not in signatures
+autodoc_typehints = "description"
+
+autodoc_default_options = {
+    'members': True,
+    'exclude-members': 'to_dict, from_dict'
+}