Improvements to documentation (MR 2440)

* Make sure all Python modules are documented by adding a bit of shell
  to .ci/docs.sh
* Remove non-existing module references from .rst
* Fix various warnings from sphinx by adjusting Python docstrings
* Add class member docs to ApkindexBlock

.ci/docs.sh

@@ -20,6 +20,22 @@ if [ -z "$(command -v sphinx-build)" ]; then
 	exit 1
 fi
 
+# Sanity check docs that all modules are documented.
+# Ignore all packages and files named test*
+fail=0
+modules="$(find pmb/ -name "*.py" | grep -v '/__init__.py' | grep -v '/test' | grep -v '/conftest.py' | sort | sed 's|\.py$||' | sed 's|/|.|g')"
+for module in $modules; do
+    if ! grep -q "automodule:: $module" docs/api/*.rst; then
+        echo "Undocumented module: $module"
+        fail=1
+    fi
+done
+if [ "$fail" -eq 1 ]; then
+    echo "ERROR: Found undocumented modules!"
+    echo "ERROR: Please add this module to the correct .rst file in docs/api/"
+    exit 1
+fi
+
 sphinx-build \
 	docs \
 	public \

docs/api/pmb.build.rst

@@ -12,6 +12,14 @@ pmb.build.autodetect module
    :undoc-members:
    :show-inheritance:
 
+pmb.build.backend module
+------------------------
+
+.. automodule:: pmb.build.backend
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 pmb.build.checksum module
 -------------------------
 
@@ -60,6 +68,14 @@ pmb.build.other module
    :undoc-members:
    :show-inheritance:
 
+pmb.build._package module
+-------------------------
+
+.. automodule:: pmb.build._package
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Module contents
 ---------------
 

docs/api/pmb.chroot.rst

@@ -68,10 +68,10 @@ pmb.chroot.other module
    :undoc-members:
    :show-inheritance:
 
-pmb.chroot.root module
+pmb.chroot.run module
-----------------------
+---------------------
 
-.. automodule:: pmb.chroot.root
+.. automodule:: pmb.chroot.run
    :members:
    :undoc-members:
    :show-inheritance:
@@ -84,14 +84,6 @@ pmb.chroot.shutdown module
    :undoc-members:
    :show-inheritance:
 
-pmb.chroot.user module
-----------------------
-
-.. automodule:: pmb.chroot.user
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 pmb.chroot.zap module
 ---------------------
 

docs/api/pmb.commands.rst

@@ -0,0 +1,101 @@
+pmb.commands package
+====================
+
+Submodules
+----------
+
+pmb.commands.aportgen module
+----------------------------
+
+.. automodule:: pmb.commands.aportgen
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pmb.commands.base module
+------------------------
+
+.. automodule:: pmb.commands.base
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pmb.commands.index module
+-------------------------
+
+.. automodule:: pmb.commands.index
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pmb.commands.kconfig_check module
+---------------------------------
+
+.. automodule:: pmb.commands.kconfig_check
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pmb.commands.kconfig_edit module
+--------------------------------
+
+.. automodule:: pmb.commands.kconfig_edit
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pmb.commands.log module
+-----------------------
+
+.. automodule:: pmb.commands.log
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pmb.commands.pkgrel_bump module
+-------------------------------
+
+.. automodule:: pmb.commands.pkgrel_bump
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pmb.commands.pkgver_bump module
+-------------------------------
+
+.. automodule:: pmb.commands.pkgver_bump
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pmb.commands.pull module
+------------------------
+
+.. automodule:: pmb.commands.pull
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pmb.commands.repo_bootstrap module
+----------------------------------
+
+.. automodule:: pmb.commands.repo_bootstrap
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pmb.commands.shutdown module
+----------------------------
+
+.. automodule:: pmb.commands.shutdown
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: pmb.commands
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/pmb.config.rst

@@ -4,6 +4,14 @@ pmb.config package
 Submodules
 ----------
 
+pmb.config.file module
+----------------------
+
+.. automodule:: pmb.config.file
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 pmb.config.init module
 ----------------------
 
@@ -12,18 +20,10 @@ pmb.config.init module
    :undoc-members:
    :show-inheritance:
 
-pmb.config.load module
+pmb.config.other module
-----------------------
+-----------------------
 
-.. automodule:: pmb.config.load
+.. automodule:: pmb.config.other
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-pmb.config.merge\_with\_args module
------------------------------------
-
-.. automodule:: pmb.config.merge_with_args
    :members:
    :undoc-members:
    :show-inheritance:
@@ -36,14 +36,6 @@ pmb.config.pmaports module
    :undoc-members:
    :show-inheritance:
 
-pmb.config.save module
-----------------------
-
-.. automodule:: pmb.config.save
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 pmb.config.sudo module
 ----------------------
 

docs/api/pmb.core.rst

@@ -0,0 +1,85 @@
+pmb.core package
+=================
+
+Submodules
+----------
+
+pmb.core.apkindex_block module
+------------------------------
+
+.. automodule:: pmb.core.apkindex_block
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pmb.core.arch module
+--------------------
+
+.. automodule:: pmb.core.arch
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pmb.core.chroot module
+----------------------
+
+.. automodule:: pmb.core.chroot
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pmb.core.config module
+----------------------
+
+.. automodule:: pmb.core.config
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pmb.core.context module
+-----------------------
+
+.. automodule:: pmb.core.context
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pmb.core.crosstool module
+-------------------------
+
+.. automodule:: pmb.core.crosstool
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pmb.core.dps module
+-------------------
+
+.. automodule:: pmb.core.dps
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pmb.core.package_metadata module
+--------------------------------
+
+.. automodule:: pmb.core.package_metadata
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+pmb.core.pkgrepo module
+-----------------------
+
+.. automodule:: pmb.core.pkgrepo
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: pmb.core
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/pmb.helpers.rst

@@ -44,6 +44,14 @@ pmb.helpers.devices module
    :undoc-members:
    :show-inheritance:
 
+pmb.helpers.exceptions module
+-----------------------------
+
+.. automodule:: pmb.helpers.exceptions
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 pmb.helpers.file module
 -----------------------
 
@@ -172,6 +180,14 @@ pmb.helpers.status module
    :undoc-members:
    :show-inheritance:
 
+pmb.helpers.toml module
+-----------------------
+
+.. automodule:: pmb.helpers.toml
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 pmb.helpers.ui module
 ---------------------
 

docs/api/pmb.install.rst

@@ -52,6 +52,14 @@ pmb.install.ui module
    :undoc-members:
    :show-inheritance:
 
+pmb.install._install module
+---------------------------
+
+.. automodule:: pmb.install._install
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Module contents
 ---------------
 

docs/api/pmb.parse.rst

@@ -12,14 +12,6 @@ pmb.parse.apkindex module
    :undoc-members:
    :show-inheritance:
 
-pmb.parse.arch module
----------------------
-
-.. automodule:: pmb.parse.arch
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 pmb.parse.arguments module
 --------------------------
 
@@ -76,6 +68,14 @@ pmb.parse.kconfig module
    :undoc-members:
    :show-inheritance:
 
+pmb.parse.kconfigcheck module
+-----------------------------
+
+.. automodule:: pmb.parse.kconfigcheck
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 pmb.parse.version module
 ------------------------
 
@@ -84,6 +84,14 @@ pmb.parse.version module
    :undoc-members:
    :show-inheritance:
 
+pmb.parse._apkbuild module
+--------------------------
+
+.. automodule:: pmb.parse._apkbuild
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 Module contents
 ---------------
 

docs/api/pmb.rst

@@ -11,7 +11,9 @@ Subpackages
    pmb.build
    pmb.chroot
    pmb.ci
+   pmb.commands
    pmb.config
+   pmb.core
    pmb.export
    pmb.flasher
    pmb.helpers
@@ -20,6 +22,7 @@ Subpackages
    pmb.parse
    pmb.qemu
    pmb.sideload
+   pmb.types
 
 Module contents
 ---------------

docs/api/pmb.types.rst

@@ -0,0 +1,10 @@
+pmb.types package
+=================
+
+Module contents
+---------------
+
+.. automodule:: pmb.types
+   :members:
+   :undoc-members:
+   :show-inheritance:

pmb/aportgen/__init__.py

@@ -24,11 +24,10 @@ def get_cross_package_arches(pkgname: str) -> str:
     :param pkgname: package name, e.g. "gcc-aarch64", "gcc-x86_64"
 
     :returns: string of architecture(s) (space separated). It doesn't
-    necessarily make sense to use Arch here given that this value gets
+              necessarily make sense to use Arch here given that this value gets
-    used to write APKBUILD files, where the ``arch`` field can have values
+              used to write APKBUILD files, where the ``arch`` field can have values
-    that aren't necessarily valid arches like "!armhf", "noarch", or
+              that aren't necessarily valid arches like "!armhf", "noarch", or
-    "x86 x86_64".
+              "x86 x86_64".
-
     """
     if pkgname.endswith("-x86_64"):
         return "aarch64"
@@ -46,7 +45,6 @@ def properties(pkgname):
     :param pkgname: package name
 
     :returns: (prefix, folder, options)
-
     """
     for folder, options in pmb.config.aportgen.items():
         for prefix in options["prefixes"]:

pmb/core/apkindex_block.py

@@ -8,17 +8,23 @@ from pmb.core.arch import Arch
 @dataclass
 class ApkindexBlock:
     """
-    "depends" is not set for packages without any dependencies, e.g. ``musl``.
-
     "timestamp" and "origin" are not set for virtual packages (#1273).
     We use that information to skip these virtual packages in parse().
     """
 
+    #: the architecture of the package
     arch: Arch
+    #: dependencies for the package
     depends: list[str]
+    #: the origin name of the package
     origin: str | None
+    #: package name
     pkgname: str
+    #: what this package provides
     provides: list[str]
+    #: provider priority for the package
     provider_priority: int | None
+    #: unix timestamp of the package build date/time
     timestamp: str | None
+    #: package version
     version: str

pmb/helpers/mount.py

@@ -104,6 +104,7 @@ def umount_all(folder: Path):
 def mount_device_rootfs(chroot_rootfs: Chroot, chroot_base: Chroot = Chroot.native()) -> PurePath:
     """
     Mount the device rootfs.
+
     :param chroot_rootfs: the chroot where the rootfs that will be
                           installed on the device has been created (e.g.
                           "rootfs_qemu-amd64")

pmb/parse/_apkbuild.py

@@ -144,11 +144,10 @@ def parse_next_attribute(lines, i, path):
     pkgrel=3
     options="!check" # ignore this comment
     arch='all !armhf'
-    depends="
+    depends="first-pkg
-        first-pkg
+    second-pkg"
-        second-pkg"
 
-    :param lines: \n-terminated list of lines from the APKBUILD
+    :param lines: newline-terminated list of lines from the APKBUILD
     :param i: index of the line we are currently looking at
     :param path: full path to the APKBUILD (for error message)
     :returns: (attribute, value, i)
@@ -380,8 +379,7 @@ def kernels(device: str):
     :returns: None when the kernel is hardcoded in depends
     :returns: kernel types and their description (as read from the subpackages)
               possible types: "downstream", "stable", "mainline"
-              example: {"mainline": "Mainline description",
+              example: {"mainline": "Mainline description", "downstream": "Downstream description"}
-                        "downstream": "Downstream description"}
     """
     # Read the APKBUILD
     apkbuild_path = pmb.helpers.devices.find_path(device, "APKBUILD")