docs: Improve tuf.api docs

Write a bit more about the two modules, hide the actual TOC to not repeat (and not have sphinx complain about missing items in TOC) Signed-off-by: Jussi Kukkonen <[email protected]>
theupdateframework · Aug 23, 2021 · 27bbcb1 · 27bbcb1
1 parent eaf0f6d
commit 27bbcb1
Showing 1 changed file with 7 additions and 4 deletions.
diff --git a/docs/api/tuf.api.rst b/docs/api/tuf.api.rst
@@ -1,10 +1,13 @@
 Metadata API
 ===============
 
-.. toctree::
-   :maxdepth: 4
+The low-level Metadata API contains two modules:
 
-   tuf.api.serialization
-   tuf.api.metadata
+* :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).
 
+.. toctree::
+   :hidden:
 
+   tuf.api.metadata
+   tuf.api.serialization