[elbe-devel] [PATCH] elbevalidate: add API docs

[Thomas Weißschuh]

Signed-off-by: Thomas Weißschuh <thomas.weissschuh at linutronix.de>
---
 docs/conf.py             |  8 +++++++
 docs/elbevalidate.rst    | 13 +++++++++++
 docs/index.rst           |  1 +
 elbevalidate/__init__.py | 59 +++++++++++++++++++++++++++++++++++++++++++++++-
 elbevalidate/path.py     |  9 ++++----
 5 files changed, 84 insertions(+), 6 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index 44be66dcfac0..3cefa58e8770 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -36,7 +36,9 @@ from elbepack.version import elbe_version  # noqa: E402
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'sphinx.ext.autodoc',
     'sphinx.ext.graphviz',
+    'sphinx.ext.intersphinx',
     'xmlschema',
 ]
 
@@ -84,6 +86,12 @@ pygments_style = 'sphinx'
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
+# manpages.debian.org/{path} seems to be broken
+manpages_url = 'https://man.archlinux.org/search?q={path}'
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+}
 
 # -- Options for HTML output ----------------------------------------------
 
diff --git a/docs/elbevalidate.rst b/docs/elbevalidate.rst
new file mode 100644
index 000000000000..99479b41ccc4
--- /dev/null
+++ b/docs/elbevalidate.rst
@@ -0,0 +1,13 @@
+The elbevalidate module
+=======================
+
+.. automodule:: elbevalidate
+   :members:
+
+.. autoclass:: elbevalidate.path.Path
+   :members:
+   :undoc-members:
+
+.. automodule:: elbevalidate.constants
+   :members:
+   :undoc-members:
diff --git a/docs/index.rst b/docs/index.rst
index a9592ebdbf8f..bbd4319977b5 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -11,6 +11,7 @@ ELBE docs
    article-quickstart
    article-elbeoverview-en
    article-elbe-schema-reference
+   elbevalidate
 
 .. toctree::
    :maxdepth: 1
diff --git a/elbevalidate/__init__.py b/elbevalidate/__init__.py
index c43bfb50c47e..6e26d65ab695 100644
--- a/elbevalidate/__init__.py
+++ b/elbevalidate/__init__.py
@@ -1,3 +1,19 @@
+"""
+Utility to validate the contents of a created image.
+The image is not booted but only mounted safely through libguestfs.
+
+Example usage:
+
+.. code:: python
+
+    with Image.from_file('sda.img') as image:
+        for partition in image.partitions:
+            print(partition)
+
+        with image.files() as root:
+            print(root.joinpath('etc', 'hostname').read_text())
+"""
+
 import abc
 import collections
 import contextlib
@@ -13,17 +29,30 @@ from elbevalidate.path import Path as ImagePath
 
 
 class BlockDevice(abc.ABC):
+    """
+    The abstract interface for block devices.
+    """
+
     @property
     @abc.abstractmethod
     def size(self) -> int:
+        """ Size in bytes. """
         pass
 
     @abc.abstractmethod
     def blkid(self) -> dict:
+        """
+        Device attributes as detected by :command:`blkid`.
+
+        For common tags, see :manpage:`libblkid(3)`.
+        """
         pass
 
     @abc.abstractmethod
     def files(self) -> typing.ContextManager[ImagePath]:
+        """
+        Access to the files as found inside the block device.
+        """
         pass
 
 
@@ -36,10 +65,25 @@ def _blkid(instance):
 
 @dataclasses.dataclass
 class Partition(BlockDevice):
+    """ A single partition """
+
     _parent: BlockDevice = dataclasses.field(repr=False)
+
     number: int
+    """ Number of the partition, starting at 1 """
+
     type: str
+    """
+
+    Type of the partition. One of
+
+    * a GPT UUID (see :py:class:`elbevalidate.constants.GPTPartitionType`)
+    * a DOS partition type number, formatted as hex
+    """
+
     start: int
+    """ Start offset of the partition in the :py:class:`Image`, in bytes."""
+
     _size: int
 
     def __post_init__(self):
@@ -67,9 +111,15 @@ class Partition(BlockDevice):
 
 
 @dataclasses.dataclass
-class PartitionTable:
+class PartitionTable(collections.abc.Sequence):
+    """ List of :py:class:`Partition` inside an :py:class:`Image`. """
+
     label: PartitionLabel
+    """ Type of the partition table. """
+
     sector_size: int
+    """ Size of each sector in bytes. """
+
     _partitions: list[Partition]
 
     def __len__(self):
@@ -80,6 +130,10 @@ class PartitionTable:
 
 
 class Image(BlockDevice):
+    """
+    A full system image, containing a :py:class:`PartitionTable` with :py:class:`Partition`.
+    """
+
     def __init__(self, gfs):
         self._gfs = gfs
         self._gfs_blockdev = '/dev/sda'
@@ -87,6 +141,7 @@ class Image(BlockDevice):
     @classmethod
     @contextlib.contextmanager
     def from_file(cls, image) -> collections.abc.Generator[typing.Self, None, None]:
+        """ Construct an :py:class:`Image` from a local file. """
         gfs = guestfs.GuestFS(python_return_dict=True)
         instance = cls(gfs)
 
@@ -113,6 +168,7 @@ class Image(BlockDevice):
 
     @functools.cached_property
     def partitions(self) -> PartitionTable:
+        """ Partitions contained in this image. """
         parttype = self._gfs.part_get_parttype(self._gfs_blockdev)
         gfs_parts = self._gfs.part_list(self._gfs_blockdev)
 
@@ -151,4 +207,5 @@ class Image(BlockDevice):
 
 # This is a module-level API in the stdlib, so we do the same here.
 def statvfs(path: ImagePath):
+    """ An equivalent of :py:func:`os.statvfs` working with :py:class:`elbevalidate.path.Path`. """
     return path._statvfs()
diff --git a/elbevalidate/path.py b/elbevalidate/path.py
index 36b7c4cbc346..e76465006459 100644
--- a/elbevalidate/path.py
+++ b/elbevalidate/path.py
@@ -1,5 +1,5 @@
 """
-Classes mimicking pathlib.Path-like that operate on files within a libguestfs context.
+Classes mimicking :py:class:`pathlib.Path` that operate on files within a libguestfs context.
 """
 
 import contextlib
@@ -10,7 +10,7 @@ import pathlib
 
 class _PurePath:
     """
-    Reference to a path inside an image.
+    Reference to a path inside an block device.
     API is the same as of pathlib.
 
     Pure variant that only provides path-manipulation methods.
@@ -108,10 +108,9 @@ def _guestfs_ctx():
 
 class Path(_PurePath):
     """
-    Reference to a path inside an image.
-    API is the same as of pathlib.
+    Reference to a path inside a :py:class:`elbevalidate.BlockDevice`.
 
-    Normal variant containing IO functionality.
+    For documentation see :py:mod:`pathlib`.
     """
 
     def iterdir(self):

---
base-commit: 39ea87de6d1549ab361ffd02cadf8d84abe50900
change-id: 20240611-elbevalidate-docs-16a140c210a0

Best regards,
-- 
Thomas Weißschuh <thomas.weissschuh at linutronix.de>