WIP CHANGES

docs/Makefile

@@ -14,7 +14,7 @@ cleanbuild:
 	@$(MAKE) html
 
 clean:
-	rm -rf html source/cli .buildinfo .doctrees versions checkouts
+	rm -rf html source/cli source/code .buildinfo .doctrees versions checkouts
 
 html:
 	sphinx-build $(SPHINXARGS) $(buildargs) html

docs/source/cli.md

@@ -1,7 +1,7 @@
 # CLI Interface
 
 ```{eval-rst}
-.. click:: main:cli
+.. click:: kupferbootstrap.main:cli
    :nested: none
    :prog: kupferbootstrap
 

docs/source/cmd.md

@@ -6,6 +6,7 @@ orphan: true
 only used to trigger builds of the submodule docs!
 
 ```{eval-rst}
+.. currentmodule:: kupferbootstrap
 .. autosummary::
    :toctree: cli
    :template: command.rst

docs/source/conf.py

@@ -1,10 +1,14 @@
+import logging
 import os
-import sys
+from sphinx.config import getenv
+from kupferbootstrap.utils import git
 
-sys.path.insert(0, os.path.abspath('../..'))
+#sys.path.insert(0, os.path.abspath('../..'))
 extensions = [
     'sphinx_click',
-    'sphinx.ext.autosummary',  # Create neat summary tables
+    "sphinx.ext.autodoc",
+    'sphinx.ext.autosummary',
+    "sphinx.ext.linkcode",
     'myst_parser'
 ]
 myst_all_links_external = True
@@ -29,4 +33,45 @@ html_theme_options = {
         "color-brand-content": "#eba38d",
         "color-problematic": "#ff7564",
     },
+    "source_repository": "https://gitlab.com/kupfer/kupferbootstrap",
+    "source_directory": "docs/source/",
 }
+
+
+autosummary_generate = True
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+    "show-inheritance": True,
+    "inherited-members": True,
+}
+autodoc_preserve_defaults = True
+
+
+def get_version():
+    try:
+        res = git(
+            ["rev-parse", "HEAD"],
+            dir=os.path.join(os.path.dirname(__file__), "../.."),
+            use_git_dir=True,
+            capture_output=True,
+        )
+        res.check_returncode()
+        ver = res.stdout.decode().strip()
+        logging.info(f"Detected git {ver=}")
+        return ver
+    except Exception as ex:
+        logging.warning("Couldn't get git branch:", exc_info=ex)
+        return "HEAD"
+
+
+version = getenv("version") or get_version()
+
+
+def linkcode_resolve(domain, info):
+    if domain != 'py':
+        return None
+    if not info['module']:
+        return None
+    filename = info['module'].replace('.', '/')
+    return "%s/-/blob/%s/src/%s.py" % (html_theme_options["source_repository"], version, filename)

docs/source/index.md

@@ -8,4 +8,6 @@ a tool to build and flash packages and images for the [Kupfer](https://gitlab.co
 ```{toctree}
 usage/index
 cli
+code
+genindex
 ```

docs/source/templates/command.rst

@@ -1,6 +1,9 @@
-.. title: {{fullname}}
+{% set reduced_name = fullname.split(".", 1)[-1] if fullname.startswith("kupferbootstrap.") else fullname %}
+.. title: {{reduced_name}}
 
-.. click:: {% if fullname == 'main' %}main:cli{% else %}{{fullname}}.cli:cmd_{{fullname}}{% endif %}
+
-  :prog: kupferbootstrap {{fullname}}
+.. currentmodule:: {{ fullname }}
+.. click:: {% if fullname == 'main' %}kupferbootstrap.main:cli{% else %}{{fullname}}.cli:cmd_{{reduced_name}}{% endif %}
+  :prog: kupferbootstrap {{reduced_name}}
   :nested: full
 

src/kupferbootstrap/devices/deviceinfo.py

@@ -205,15 +205,12 @@ def parse_kernel_suffix(deviceinfo: dict[str, Optional[str]], kernel: str = 'mai
     https://wiki.postmarketos.org/wiki/Device_specific_package#Multiple_kernels
 
     :param info: deviceinfo dict, e.g.:
-                 {"a": "first",
+        {"a": "first", "b_mainline": "second", "b_downstream": "third"}
-                  "b_mainline": "second",
-                  "b_downstream": "third"}
     :param device: which device info belongs to
     :param kernel: which kernel suffix to remove (e.g. "mainline")
     :returns: info, but with the configured kernel suffix removed, e.g:
-              {"a": "first",
+        {"a": "first", "b": "second", "b_downstream": "third"}
-               "b": "second",
+
-               "b_downstream": "third"}
     """
     # Do nothing if the configured kernel isn't available in the kernel (e.g.
     # after switching from device with multiple kernels to device with only one

src/kupferbootstrap/wrapper/__init__.py

@@ -57,10 +57,12 @@ def wrap_if_foreign_arch(arch: Arch):
 
 
 def execute_without_exit(f, argv_override: Optional[list[str]], *args, **kwargs):
-    """If no wrap is needed, executes and returns f(*args, **kwargs).
+    """
+    If no wrap is needed, executes and returns `f(*args, **kwargs)`.
     If a wrap is determined to be necessary, force a wrap with argv_override applied.
     If a wrap was forced, None is returned.
-    WARNING: No protection against f() returning None is taken."""
+    WARNING: No protection against f() returning None is taken.
+    """
     if not needs_wrap():
         return f(*args, **kwargs)
     assert get_wrapper_type() != 'none', "needs_wrap() should've returned False"