gardenlinux · ByteOtter · Mar 26, 2026 · Apr 1, 2026 · Apr 14, 2026 · Apr 14, 2026
diff --git a/README.md b/README.md
@@ -1,14 +1,17 @@
+## Garden Linux Python Library
+
 ![poetry build](https://github.com/gardenlinux/parse_features_lib/actions/workflows/build.yml/badge.svg)
 ![Black Lint](https://github.com/gardenlinux/parse_features_lib/actions/workflows/black.yml/badge.svg)
 ![Test](https://github.com/gardenlinux/parse_features_lib/actions/workflows/pytests.yml/badge.svg)
 ![security check](https://github.com/gardenlinux/parse_features_lib/actions/workflows/bandit.yml/badge.svg)
 
-## Garden Linux Python Library
-
-Python tooling to work with [Garden Linux](https://github.com/gardenlinux/gardenlinux) features, flavors, OCI artifacts, repositories, and releases.
-It is primarily targeted at Garden Linux developers and CI pipelines rather than end users.
+Python tooling to work with
+[Garden Linux](https://github.com/gardenlinux/gardenlinux) features, flavors,
+OCI artifacts, repositories, and releases. It is primarily targeted at Garden
+Linux developers and CI pipelines rather than end users.
 
-The library follows the intent of [Semantic Versioning](https://semver.org) for its public APIs.
+The library follows the intent of [Semantic Versioning](https://semver.org) for
+its public APIs.
 
 ### Features
 
@@ -21,59 +24,45 @@ The library follows the intent of [Semantic Versioning](https://semver.org) for
 
 ## Documentation
 
-Full documentation is available at the **Garden Linux Python Library Documentation** site:
-[https://gardenlinux.github.io/python-gardenlinux-lib/](https://gardenlinux.github.io/python-gardenlinux-lib/)
-
-The docs include:
-
-- **Command-Line Interface**: `gl-features-*`, `gl-flavors-*`, `gl-oci`, `gl-s3`, `gl-gh-release`
-- **API Reference**: modules, classes, and functions (e.g. `Parser`, `CName`, `Container`, `Repository`)
-- **Release documentation**: versioning and release process
-
-## Installation
+You can find a full documentation about how to
+[install this python library](https://gardenlinux-docs.netlify.app/reference/supporting_tools/python-gardenlinux-lib.html#installation)
+and
+[use its CLI interface](https://gardenlinux-docs.netlify.app/reference/python-gardenlinux-lib-cli.html)
+this on our [documentation hub](https://gardenlinux-docs.netlify.app/).
 
-### Using `poetry` (from Git)
+For a detailed API documentation, check
+[gardenlinux.github.io/python-gardenlinux-lib/api.html](https://gardenlinux.github.io/python-gardenlinux-lib/)
 
-Add the library as a dependency in your `pyproject.toml`:
+# Community
 
-```toml
-[tool.poetry.dependencies]
-gardenlinux = { git = "https://github.com/gardenlinux/python-gardenlinux-lib", rev = "0.10.5" }
-```
+To stay up-to-date with recent news about Gardenlinux, subscribe to our mailing
+list:
 
-Then install:
+https://lists.neonephos.org/g/gardenlinux-discussion
 
-```bash
-poetry install
-```
+For updates and statements regarding security issues, we have a security mailing
+list for you:
 
-### Local development setup
+https://lists.neonephos.org/g/gardenlinux-security
 
-```bash
-git clone https://github.com/gardenlinux/python-gardenlinux-lib.git
-cd python-gardenlinux-lib
-python -m venv venv
-source venv/bin/activate
-poetry install
-```
+For embargoed security related topics, this list is for you:
 
-## Quickstart
+https://lists.neonephos.org/g/gardenlinux-security-embargo
 
-### Example: list features for a given `cname`
+# Contributing
 
-```python
-from gardenlinux.features import Parser
+We welcome your contributions to Gardenlinux or any supporting projects.
 
-cname = "aws-gardener_prod"
-feature_list = Parser().filter_as_list(cname)
+To find our more, visit our
+[Contributor Documentation](https://gardenlinux-docs.netlify.app/contributing).
 
-print(f"features of {cname}:")
-for feature in feature_list:
-    print(feature)
-```
+## Licensing
 
-For more examples and for all CLI tools, see the **Command-Line Interface** and **API Reference** sections in the docs:
-[https://gardenlinux.github.io/python-gardenlinux-lib/](https://gardenlinux.github.io/python-gardenlinux-lib/)
+Copyright 2025 SAP SE or an SAP affiliate company and GardenLinux contributors.
+Please see our [LICENSE](LICENSE.md) for copyright and license information.
+Detailed information including third-party components and their
+licensing/copyright information is available
+[via the REUSE tool](https://reuse.software).
 
 <p align="center">
   <img alt="Bundesministerium für Wirtschaft und Energie (BMWE)-EU funding logo" src="https://apeirora.eu/assets/img/BMWK-EU.png" width="400"/>

diff --git a/docs/Makefile b/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).

diff --git a/docs/api.rst b/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:
diff --git a/docs/cli.rst b/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
 -----------------

diff --git a/docs/conf.py b/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"]

diff --git a/docs/contributing/.gitkeep b/docs/contributing/.gitkeep
diff --git a/docs/explanation/.gitkeep b/docs/explanation/.gitkeep
diff --git a/docs/how-to/release.md b/docs/how-to/release.md
@@ -0,0 +1,70 @@
+---
+title: Python Library - Release Process
+description: Release a new version of the Garden Linux Python Library
+related_topics:
+  - /reference/supporting_tools/python-gardenlinux-lib
+  - /reference/python-gardenlinux-lib-cli
+  - /how-to/python-gardenlinux-lib-release
+migration_status: "done"
+migration_stakeholder: "@tmangold, @yeoldegrove, @ByteOtter"
+migration_approved: false
+github_org: gardenlinux
+github_repo: python-gardenlinux-lib
+github_source_path: docs/how-to/release.md
+github_target_path: docs/how-to/python-gardenlinux-lib-release.md
+---
+
+# Release Documentation
+
+_python-gardenlinux-lib_ strictly follows the syntax and intention of
+[Semantic Versioning](https://www.semver.org). Each release reflects the
+intention and expected impact therefore.
+
+A new release is done by tagging a commit with a valid version. This will create
+a GitHub pre-release for proof-reading. Once done a new release can be published
+using GitHub CLI or UI.
+
+Newly added docstrings should contain the first version supporting the new API /
+command line.
+
+## Step by Step Guide
+
+1. **Set version files:**
+
+   _python-gardenlinux-lib_ versioning needs to be set in:
+   - `pyproject.toml`
+   - `.github/actions/setup/action.yml`
+
+   Additionally at the moment (removal pending):
+   - `.github/actions/features_parse/action.yml`
+   - `.github/actions/flavors_parse/action.yml`
+
+2. **Create git tag:**
+
+   ```bash
+   git tag <tag>
+   ```
+
+3. **Review and publish:**
+
+   Review the generated pre-release changelog by visiting the GitHub project
+   release page and publish it if applicable.
+
+4. **Consume the library:**
+
+   Projects consuming the _python-gardenlinux-lib_ may use the following git URL
+   for dependency definition:
+
+   ```bash
+   pip install git+https://github.com/gardenlinux/python-gardenlinux-lib.git@1.0.0
+   ```
+
+   Or in `requirements.txt`:
+
+   ```
+   gardenlinux @ git+https://github.com/gardenlinux/python-gardenlinux-lib.git@1.0.0
+   ```
+
+## Related Topics
+
+<RelatedTopics />
diff --git a/docs/index.rst b/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.
 

diff --git a/docs/overview/index.md b/docs/overview/index.md
@@ -0,0 +1,102 @@
+---
+title: "Python Library"
+description: An overview of the Garden Linux Python Library
+related_topics:
+  - /reference/supporting_tools/python-gardenlinux-lib
+  - /reference/python-gardenlinux-lib-cli
+  - /how-to/python-gardenlinux-lib-release
+migration_status: "done"
+migration_stakeholder: "@tmangold, @yeoldegrove, @ByteOtter"
+migration_approved: false
+github_org: gardenlinux
+github_repo: python-gardenlinux-lib
+github_source_path: docs/overview/index.md
+github_target_path: "docs/reference/supporting_tools/python-gardenlinux-lib.md"
+---
+
+# Garden Linux Python Library Documentation
+
+Welcome to the Garden Linux Python Library documentation. This library provides
+Python tools and utilities for working with Garden Linux features, flavors, OCI
+artifacts, S3 buckets, and GitHub releases.
+
+## Overview
+
+The Garden Linux Python Library is a comprehensive toolkit for managing and
+interacting with Garden Linux components. It includes:
+
+- **Feature Management**: Parse and work with Garden Linux features and generate
+  canonical names
+- **Flavor Processing**: Parse flavors.yaml and generate combinations
+- **OCI Operations**: Push OCI artifacts to registries and manage manifests
+- **S3 Integration**: Upload and download artifacts from S3 buckets
+- **GitHub Integration**: Create and manage GitHub releases with release notes
+
+## Installation
+
+### Using `poetry` (from Git)
+
+Add the library as a dependency in your `pyproject.toml`:
+
+```toml
+[tool.poetry.dependencies]
+gardenlinux = { git = "https://github.com/gardenlinux/python-gardenlinux-lib", rev = "0.10.5" }
+```
+
+Then install:
+
+```bash
+poetry install
+```
+
+### Local development setup
+
+```bash
+git clone https://github.com/gardenlinux/python-gardenlinux-lib.git
+cd python-gardenlinux-lib
+python -m venv venv
+source venv/bin/activate
+poetry install
+```
+
+## Quickstart
+
+### Example: list features for a given `cname`
+
+```python
+from gardenlinux.features import Parser
+
+cname = "aws-gardener_prod"
+feature_list = Parser().filter_as_list(cname)
+
+print(f"features of {cname}:")
+for feature in feature_list:
+    print(feature)
+```
+
+For more examples and for all CLI tools, see the **Command-Line Interface** and
+**API Reference** sections in the docs:
+[https://gardenlinux.github.io/python-gardenlinux-lib/](https://gardenlinux.github.io/python-gardenlinux-lib/)
+
+## Quick Start
+
+### Command-Line Interface
+
+The library provides several command-line tools for common operations. See the
+[Command-Line Interface documentation](/reference/python-gardenlinux-lib-cli.md)
+for detailed information about all available commands.
+
+### Release Management
+
+For information about versioning and release procedures, see the
+[Release documentation](/how-to/python-gardenlinux-lib-release.md).
+
+### API Reference
+
+For detailed Python API documentation, including all modules, classes, and
+functions, see the
+[API Reference on ReadTheDocs](https://gardenlinux.github.io/python-gardenlinux-lib/api.html).
+
+## Related Topics
+
+<RelatedTopics />
diff --git a/docs/reference/.gitkeep b/docs/reference/.gitkeep
diff --git a/docs/tutorials/.gitkeep b/docs/tutorials/.gitkeep
diff --git a/pyproject.toml b/pyproject.toml
@@ -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"

diff --git a/test-data/gardenlinux b/test-data/gardenlinux