diff --git a/docs/Makefile b/docs/Makefile index 7255957..48a3aee 100644 --- a/docs/Makefile +++ b/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 diff --git a/docs/source/cli.md b/docs/source/cli.md index 53847fb..eb08e1f 100644 --- a/docs/source/cli.md +++ b/docs/source/cli.md @@ -1,7 +1,7 @@ # CLI Interface ```{eval-rst} -.. click:: main:cli +.. click:: kupferbootstrap.main:cli :nested: none :prog: kupferbootstrap diff --git a/docs/source/cmd.md b/docs/source/cmd.md index 646372d..976d4eb 100644 --- a/docs/source/cmd.md +++ b/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 diff --git a/docs/source/conf.py b/docs/source/conf.py index fe0dc90..6ab8a57 100644 --- a/docs/source/conf.py +++ b/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) diff --git a/docs/source/index.md b/docs/source/index.md index 2cde0d6..df03035 100644 --- a/docs/source/index.md +++ b/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 ``` diff --git a/docs/source/templates/command.rst b/docs/source/templates/command.rst index 977c023..da9a9ec 100644 --- a/docs/source/templates/command.rst +++ b/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 diff --git a/src/kupferbootstrap/devices/deviceinfo.py b/src/kupferbootstrap/devices/deviceinfo.py index 72abdc0..b22ee45 100644 --- a/src/kupferbootstrap/devices/deviceinfo.py +++ b/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", - "b_mainline": "second", - "b_downstream": "third"} + {"a": "first", "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", - "b": "second", - "b_downstream": "third"} + {"a": "first", "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 diff --git a/src/kupferbootstrap/wrapper/__init__.py b/src/kupferbootstrap/wrapper/__init__.py index ea16f34..1a7156e 100644 --- a/src/kupferbootstrap/wrapper/__init__.py +++ b/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"