Refine Sphinx documentation generation

Signed-off-by: Tobias Wolf <wolf@b1-systems.de>
On-behalf-of: SAP <tobias.wolf@sap.com>

Author: NotTheEvilOne

.github/workflows/docs.yml

@@ -8,7 +8,29 @@ env:
   GIT_CLIFF_VERSION: 2.12.0
 
 jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: gardenlinux/python-gardenlinux-lib/.github/actions/setup@main
+      - run: make docs
+      - if: ${{ github.ref_name != 'main' }}
+        name: Upload as artifact
+        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # pin@v6.0.0
+        with:
+          name: docs
+          path: _build/
+      - if: ${{ github.ref_name == 'main' }}
+        name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _build
+          force_orphan: true
+
   create-pre-release:
+    if: ${{ github.ref_name == 'main' }}
     runs-on: ubuntu-latest
     permissions:
       contents: write

.github/workflows/release.yml

@@ -1,5 +1,5 @@
 API Reference
-============
+=============
 
 This section provides detailed documentation for all Python modules and classes in python-gardenlinux-lib.
 

docs/api.rst

@@ -11,14 +11,14 @@ gl-cname
 
 Generate a canonical name (cname) from feature sets.
 
-.. autoprogram:: gardenlinux.features.cname_main:parser
+.. autoprogram:: gardenlinux.features.cname_main:get_parser()
 
 gl-features-parse
 ~~~~~~~~~~~~~~~~~
 
 Parse and extract information from GardenLinux features.
 
-.. autoprogram:: gardenlinux.features.__main__:parser
+.. autoprogram:: gardenlinux.features.__main__:get_parser()
 
 Flavors Commands
 ----------------
@@ -28,7 +28,7 @@ gl-flavors-parse
 
 Parse flavors.yaml and generate combinations.
 
-.. autoprogram:: gardenlinux.flavors.__main__:parser
+.. autoprogram:: gardenlinux.flavors.__main__:get_parser()
 
 OCI Commands
 ------------
@@ -50,7 +50,7 @@ gl-s3
 
 Upload and download artifacts from S3 buckets.
 
-.. autoprogram:: gardenlinux.s3.__main__:parser
+.. autoprogram:: gardenlinux.s3.__main__:get_parser()
 
 GitHub Commands
 ---------------
@@ -60,4 +60,4 @@ gl-gh-release
 
 Create and manage GitHub releases.
 
-.. autoprogram:: gardenlinux.github.release.__main__:parser
+.. autoprogram:: gardenlinux.github.release.__main__:get_parser()

docs/cli.rst

@@ -1,8 +1,4 @@
-import os
-import sys
-
-sys.path.insert(0, os.path.abspath("../src"))
-
+from sphinx.application import Sphinx
 
 # Configuration file for the Sphinx documentation builder.
 #
@@ -41,9 +37,9 @@
 
 # Logo configuration
 html_logo = "_static/gardenlinux-logo.svg"
+
 html_theme_options = {
     "logo_only": False,
-    "display_version": True,
     "prev_next_buttons_location": "bottom",
     "style_external_links": True,
     "vcs_pageview_mode": "",
@@ -57,5 +53,5 @@
 
 
 # Add custom CSS
-def setup(app):
+def setup(app: Sphinx) -> None:
     app.add_css_file("custom.css")

docs/conf.py

@@ -47,46 +47,55 @@ def get_parser() -> argparse.ArgumentParser:
     :return: ArgumentParser instance
     :since: 0.10.9
     """
+
     parser = argparse.ArgumentParser(
-        description="Parse and extract information from GardenLinux features."
+        prog="gl-features-parse",
+        description="Parse and extract information from GardenLinux features.",
     )
 
     parser.add_argument(
         "--arch",
         dest="arch",
         help="Target architecture (e.g., amd64, arm64). Overrides architecture from cname.",
     )
+
     parser.add_argument(
         "--cname",
         dest="cname",
         required=True,
         help="Canonical name (cname) to parse. Must be a valid GardenLinux canonical name.",
     )
+
     parser.add_argument(
         "--commit",
         dest="commit",
         help="Git commit hash. If not specified, will be read from COMMIT file or release file.",
     )
+
     parser.add_argument(
         "--feature-dir",
         default="features",
         help="Path to the features directory (default: 'features'). Either --feature-dir or --release-file must be provided.",
     )
+
     parser.add_argument(
         "--release-file",
         dest="release_file",
         help="Path to a release file containing cname metadata. Either --feature-dir or --release-file must be provided.",
     )
+
     parser.add_argument(
         "--default-arch",
         dest="default_arch",
         help="Default architecture to use if architecture cannot be determined from cname or other sources.",
     )
+
     parser.add_argument(
         "--default-version",
         dest="default_version",
         help="Default version to use if version cannot be determined from files or other sources.",
     )
+
     parser.add_argument(
         "--version",
         dest="version",
@@ -110,12 +119,8 @@ def get_parser() -> argparse.ArgumentParser:
             ", ".join(_ARGS_TYPE_ALLOWED)
         ),
     )
-    return parser
 
-
-# Parser object for documentation generation
-parser = get_parser()
-parser.prog = "gl-features-parse"
+    return parser
 
 
 def main() -> None:

src/gardenlinux/features/__main__.py

@@ -26,39 +26,42 @@ def get_parser() -> argparse.ArgumentParser:
     :return: ArgumentParser instance
     :since: 1.0.0
     """
+
     parser = argparse.ArgumentParser(
-        description="Generate a canonical name (cname) from feature sets."
+        prog="gl-cname",
+        description="Generate a canonical name (cname) from feature sets.",
     )
+
     parser.add_argument(
         "--arch",
         dest="arch",
         help="Target architecture (e.g., amd64, arm64). If not specified, will be determined from the cname or feature set.",
     )
+
     parser.add_argument(
         "--commit",
         dest="commit",
         help="Git commit hash. If not specified, will be read from COMMIT file in the GardenLinux root directory.",
     )
+
     parser.add_argument(
         "--feature-dir",
         default="features",
         help="Path to the features directory (default: 'features').",
     )
+
     parser.add_argument(
         "--version",
         dest="version",
         help="Version string. If not specified, will be read from VERSION file in the GardenLinux root directory.",
     )
+
     parser.add_argument(
         "cname",
         help="Canonical name (cname) to process. Must be a valid GardenLinux canonical name format.",
     )
-    return parser
 
-
-# Parser object for documentation generation
-parser = get_parser()
-parser.prog = "gl-cname"
+    return parser
 
 
 def main() -> None:

src/gardenlinux/features/cname_main.py

@@ -6,7 +6,7 @@
 """
 
 import json
-from argparse import ArgumentParser, Namespace
+from argparse import ArgumentParser
 from pathlib import Path
 from tempfile import TemporaryDirectory
 from typing import Any, List, Tuple
@@ -55,67 +55,79 @@ def get_parser() -> ArgumentParser:
     :return: ArgumentParser instance
     :since: 1.0.0
     """
+
     parser = ArgumentParser(description="Parse flavors.yaml and generate combinations.")
 
     parser.add_argument(
         "--commit",
         default=None,
         help="Commit hash to fetch flavors.yaml from GitHub. An existing 'flavors.yaml' file will be preferred.",
     )
+
     parser.add_argument(
         "--no-arch",
         action="store_true",
         help="Exclude architecture from the flavor output.",
     )
+
     parser.add_argument(
         "--include-only",
         action="append",
         default=[],
         help="Restrict combinations to those matching wildcard patterns (can be specified multiple times).",
     )
+
     parser.add_argument(
         "--exclude",
         action="append",
         default=[],
         help="Exclude combinations based on wildcard patterns (can be specified multiple times).",
     )
+
     parser.add_argument(
         "--build",
         action="store_true",
         help="Filter combinations to include only those with build enabled.",
     )
+
     parser.add_argument(
         "--publish",
         action="store_true",
         help="Filter combinations to include only those with publish enabled.",
     )
+
     parser.add_argument(
         "--test",
         action="store_true",
         help="Filter combinations to include only those with test enabled.",
     )
+
     parser.add_argument(
         "--test-platform",
         action="store_true",
         help="Filter combinations to include only platforms with test-platform: true.",
     )
+
     parser.add_argument(
         "--category",
         action="append",
         default=[],
         help="Filter combinations to include only platforms belonging to the specified categories (can be specified multiple times).",
     )
+
     parser.add_argument(
         "--exclude-category",
         action="append",
         default=[],
         help="Exclude platforms belonging to the specified categories (can be specified multiple times).",
     )
+
     parser.add_argument(
         "--json-by-arch",
         action="store_true",
         help="Output a JSON dictionary where keys are architectures and values are lists of flavors.",
     )
+
     parser.add_argument(
         "--markdown-table-by-platform",
         action="store_true",
@@ -125,29 +137,15 @@ def get_parser() -> ArgumentParser:
     return parser
 
 
-# Parser object for documentation generation
-parser = get_parser()
-parser.prog = "gl-flavors-parse"
-
-
-def parse_args() -> Namespace:
-    """
-    Parses arguments used for main()
-
-    :return: (object) Parsed argparse.ArgumentParser namespace
-    :since:  0.7.0
-    """
-    return get_parser().parse_args()
-
-
 def main() -> None:
     """
     gl-flavors-parse main()
 
     :since: 0.7.0
     """
 
-    args = parse_args()
+    parser = get_parser()
+    args = parser.parse_args()
 
     try:
         flavors_data = _get_flavors_file_data(Path(Repository().root, "flavors.yaml"))