From 35cd64086fca9b8c94abc2fbc92bf0bd4c51e717 Mon Sep 17 00:00:00 2001
From: Luca Weiss <luca@lucaweiss.eu>
Date: Sat, 19 Oct 2024 18:01:36 +0200
Subject: [PATCH] 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 | 16 ++++++
docs/api/pmb.build.rst | 16 ++++++
docs/api/pmb.chroot.rst | 14 ++---
docs/api/pmb.commands.rst | 101 +++++++++++++++++++++++++++++++++++++
docs/api/pmb.config.rst | 22 +++-----
docs/api/pmb.core.rst | 85 +++++++++++++++++++++++++++++++
docs/api/pmb.helpers.rst | 16 ++++++
docs/api/pmb.install.rst | 8 +++
docs/api/pmb.parse.rst | 24 ++++++---
docs/api/pmb.rst | 3 ++
docs/api/pmb.types.rst | 10 ++++
pmb/aportgen/__init__.py | 10 ++--
pmb/core/apkindex_block.py | 10 +++-
pmb/helpers/mount.py | 1 +
pmb/parse/_apkbuild.py | 10 ++--
15 files changed, 298 insertions(+), 48 deletions(-)
create mode 100644 docs/api/pmb.commands.rst
create mode 100644 docs/api/pmb.core.rst
create mode 100644 docs/api/pmb.types.rst
diff --git a/.ci/docs.sh b/.ci/docs.sh
index d05576a2c..2d896708b 100755
--- a/.ci/docs.sh
+++ b/.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 \
diff --git a/docs/api/pmb.build.rst b/docs/api/pmb.build.rst
index ea566018f..ca07612e4 100644
--- a/docs/api/pmb.build.rst
+++ b/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
---------------
diff --git a/docs/api/pmb.chroot.rst b/docs/api/pmb.chroot.rst
index 7ecfd8bcf..72251e065 100644
--- a/docs/api/pmb.chroot.rst
+++ b/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
---------------------
diff --git a/docs/api/pmb.commands.rst b/docs/api/pmb.commands.rst
new file mode 100644
index 000000000..fd15a1d30
--- /dev/null
+++ b/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:
diff --git a/docs/api/pmb.config.rst b/docs/api/pmb.config.rst
index 535273311..801b9d8d4 100644
--- a/docs/api/pmb.config.rst
+++ b/docs/api/pmb.config.rst
@@ -4,26 +4,26 @@ pmb.config package
Submodules
----------
-pmb.config.init module
+pmb.config.file module
----------------------
-.. automodule:: pmb.config.init
+.. automodule:: pmb.config.file
:members:
:undoc-members:
:show-inheritance:
-pmb.config.load module
+pmb.config.init module
----------------------
-.. automodule:: pmb.config.load
+.. automodule:: pmb.config.init
:members:
:undoc-members:
:show-inheritance:
-pmb.config.merge\_with\_args module
------------------------------------
+pmb.config.other module
+-----------------------
-.. automodule:: pmb.config.merge_with_args
+.. automodule:: pmb.config.other
: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
----------------------
diff --git a/docs/api/pmb.core.rst b/docs/api/pmb.core.rst
new file mode 100644
index 000000000..cd2cde028
--- /dev/null
+++ b/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:
diff --git a/docs/api/pmb.helpers.rst b/docs/api/pmb.helpers.rst
index be1f887a5..41bf155ee 100644
--- a/docs/api/pmb.helpers.rst
+++ b/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
---------------------
diff --git a/docs/api/pmb.install.rst b/docs/api/pmb.install.rst
index 26af0845f..bfc7da2ce 100644
--- a/docs/api/pmb.install.rst
+++ b/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
---------------
diff --git a/docs/api/pmb.parse.rst b/docs/api/pmb.parse.rst
index 36cc43ff2..4e125b23a 100644
--- a/docs/api/pmb.parse.rst
+++ b/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
---------------
diff --git a/docs/api/pmb.rst b/docs/api/pmb.rst
index 91a7aa9ce..2b519731c 100644
--- a/docs/api/pmb.rst
+++ b/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
---------------
diff --git a/docs/api/pmb.types.rst b/docs/api/pmb.types.rst
new file mode 100644
index 000000000..5be803724
--- /dev/null
+++ b/docs/api/pmb.types.rst
@@ -0,0 +1,10 @@
+pmb.types package
+=================
+
+Module contents
+---------------
+
+.. automodule:: pmb.types
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/pmb/aportgen/__init__.py b/pmb/aportgen/__init__.py
index 75060e3f1..e04459d1a 100644
--- a/pmb/aportgen/__init__.py
+++ b/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
- used to write APKBUILD files, where the ``arch`` field can have values
- that aren't necessarily valid arches like "!armhf", "noarch", or
- "x86 x86_64".
-
+ necessarily make sense to use Arch here given that this value gets
+ used to write APKBUILD files, where the ``arch`` field can have values
+ that aren't necessarily valid arches like "!armhf", "noarch", or
+ "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"]:
diff --git a/pmb/core/apkindex_block.py b/pmb/core/apkindex_block.py
index 0a4e5677d..e1ef0e0e1 100644
--- a/pmb/core/apkindex_block.py
+++ b/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
diff --git a/pmb/helpers/mount.py b/pmb/helpers/mount.py
index 535f98509..98f0203bd 100644
--- a/pmb/helpers/mount.py
+++ b/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")
diff --git a/pmb/parse/_apkbuild.py b/pmb/parse/_apkbuild.py
index 00be0f3bb..170fbb052 100644
--- a/pmb/parse/_apkbuild.py
+++ b/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="
- first-pkg
- second-pkg"
+ depends="first-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",
- "downstream": "Downstream description"}
+ example: {"mainline": "Mainline description", "downstream": "Downstream description"}
"""
# Read the APKBUILD
apkbuild_path = pmb.helpers.devices.find_path(device, "APKBUILD")
--
GitLab