From b746ddcfd10587a16dee0f7a7e54039ac9caa9f8 Mon Sep 17 00:00:00 2001 From: tdruez Date: Fri, 29 Aug 2025 15:27:23 +0400 Subject: [PATCH] Display the optional steps in the Pipelines autodoc #1822 Signed-off-by: tdruez --- CHANGELOG.rst | 3 +++ docs/conf.py | 20 ++++++++++++++++++++ 2 files changed, 23 insertions(+) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index e9bb66278f..716e5ab900 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -14,6 +14,9 @@ v35.4.0 (unreleased) - Resolve and load dependencies from SPDX SBOMs. https://github.com/aboutcode-org/scancode.io/issues/1145 +- Display the optional steps in the Pipelines autodoc. + https://github.com/aboutcode-org/scancode.io/issues/1822 + v35.3.0 (2025-08-20) -------------------- diff --git a/docs/conf.py b/docs/conf.py index 397075654f..296166cab7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -81,3 +81,23 @@ # user starts in light mode (Default Mode) default_dark_mode = False + + +# Display the optional steps in the Pipelines autodoc. +def autodoc_process_docstring(app, what, name, obj, options, lines): + """ + Sphinx autodoc extension hook to insert `@optional_step` groups + into the generated documentation. + + If a function or method has been decorated with ``@optional_step``, + the decorator attaches a ``.groups`` attribute to the object. + This hook inspects that attribute during autodoc processing and prepends + a short note at the top of the function’s docstring. + """ + if hasattr(obj, "groups"): + groups_str = " ".join(f":guilabel:`{group}`" for group in sorted(obj.groups)) + lines[:0] = [f"**Optional step:** {groups_str}", ""] + + +def setup(app): + app.connect("autodoc-process-docstring", autodoc_process_docstring)