docs: enable markdown docs

Signed-off-by: Eike Waldt <waldt@b1-systems.de>
On-behalf-of: SAP <eike.waldt@sap.com>

Author: yeoldegrove

docs/Makefile

@@ -12,7 +12,11 @@ BUILDDIR      = _build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+.PHONY: help markdown Makefile
+
+# Explicit markdown target: build Markdown output via sphinx-markdown-builder
+markdown:
+	@$(SPHINXBUILD) -M markdown "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

docs/api.rst

@@ -1,22 +1,34 @@
-API Reference
-=============
+Python Library - API Reference
+==============================
 
-This section provides detailed documentation for all Python modules and classes in python-gardenlinux-lib.
+Detailed documentation for all Python modules and classes in the Garden Linux Python Library
 
-.. automodule:: gardenlinux
-    :members:
+gardenlinux.apt
+~~~~~~~~~~~~~~~
 
 .. automodule:: gardenlinux.apt
     :members:
 
+gardenlinux.features
+~~~~~~~~~~~~~~~~~~~~
+
 .. automodule:: gardenlinux.features
     :members:
 
+gardenlinux.flavors
+~~~~~~~~~~~~~~~~~~~
+
 .. automodule:: gardenlinux.flavors
     :members:
 
+gardenlinux.git
+~~~~~~~~~~~~~~~
+
 .. automodule:: gardenlinux.git
     :members:
 
+gardenlinux.oci
+~~~~~~~~~~~~~~~
+
 .. automodule:: gardenlinux.oci
     :members:

docs/cli.rst

@@ -1,7 +1,7 @@
-Command-Line Interface
-======================
+Python Library - Command-Line Interface
+=======================================
 
-This page documents all available command-line tools provided by python-gardenlinux-lib.
+Available command-line tools provided by the Garden Linux Python Library
 
 Features Commands
 -----------------

docs/conf.py

@@ -22,8 +22,15 @@
     "sphinx.ext.napoleon",
     "sphinx_click",
     "sphinxcontrib.autoprogram",
+    "sphinx_markdown_builder",
 ]
 
+# Markdown builder configuration (GitHub-Flavored Markdown for VitePress)
+# We can enable this after https://github.com/liran-funaro/sphinx-markdown-builder/pull/53 is merged
+# markdown_flavor = "github"
+markdown_anchor_sections = True
+markdown_anchor_signatures = True
+
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 autodoc_mock_imports = ["networkx"]

docs/how-to/release.md

@@ -1,10 +1,10 @@
 ---
-title: Release Process - Python Library
+title: Python Library - Release Process
 description: Release a new version of the Garden Linux Python Library
 related_topics:
-  - /reference/supporting_tools/python-gardenlinux-lib.md
-  - /reference/python-gardenlinux-lib-cli.md
-  - /how-to/python-gardenlinux-lib-release.md
+  - /reference/supporting_tools/python-gardenlinux-lib
+  - /reference/python-gardenlinux-lib-cli
+  - /how-to/python-gardenlinux-lib-release
 migration_status: "new"
 migration_source: ""
 migration_issue: ""

docs/index.rst

@@ -1,7 +1,7 @@
-Garden Linux Python Library Documentation
+Garden Linux Python Library
 ==========================================
 
-Welcome to the Garden Linux Python Library documentation. This library provides
+The Garden linux Python Library provides
 Python tools and utilities for working with Garden Linux features, flavors,
 OCI artifacts, S3 buckets, and GitHub releases.
 

docs/overview/index.md

@@ -2,9 +2,9 @@
 title: "Python Library"
 description: An overview of the Garden Linux Python Library
 related_topics:
-  - /reference/supporting_tools/python-gardenlinux-lib.md
-  - /reference/python-gardenlinux-lib-cli.md
-  - /how-to/python-gardenlinux-lib-release.md
+  - /reference/supporting_tools/python-gardenlinux-lib
+  - /reference/python-gardenlinux-lib-cli
+  - /how-to/python-gardenlinux-lib-release
 migration_status: "new"
 migration_source: ""
 migration_issue: ""

docs/reference/cli.md

@@ -42,6 +42,7 @@ boto3-stubs = { extras = ["s3"], version = "^1.42.30" }
 sphinx-rtd-theme = "^3.0.2"
 sphinx-click = "^4.4.0"
 sphinxcontrib-autoprogram = "^0.1.8"
+sphinx-markdown-builder = "^0.6.10"
 
 [tool.poetry.scripts]
 gl-cname = "gardenlinux.features.cname_main:main"