diff --git a/README.md b/README.md index f6e616c1..c273595a 100644 --- 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).

Bundesministerium für Wirtschaft und Energie (BMWE)-EU funding logo diff --git a/docs/Makefile b/docs/Makefile index d4bb2cbb..c8ea8e0a 100644 --- 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 index 2d68330a..8598052f 100644 --- 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 index 80cc963c..f975b2aa 100644 --- 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 index 30c97c2f..a24c6f5f 100644 --- 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 new file mode 100644 index 00000000..e69de29b diff --git a/docs/explanation/.gitkeep b/docs/explanation/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/how-to/release.md b/docs/how-to/release.md new file mode 100644 index 00000000..00eb70a7 --- /dev/null +++ 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 + ``` + +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 + + diff --git a/docs/index.rst b/docs/index.rst index 9de35821..547111d6 100644 --- 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 new file mode 100644 index 00000000..526bf231 --- /dev/null +++ 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 + + diff --git a/docs/reference/.gitkeep b/docs/reference/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/tutorials/.gitkeep b/docs/tutorials/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/pyproject.toml b/pyproject.toml index efa07c38..7364c388 100644 --- 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 index 81d2743e..8c14e750 160000 --- a/test-data/gardenlinux +++ b/test-data/gardenlinux @@ -1 +1 @@ -Subproject commit 81d2743eed1d6d23e675033e7960734e32e8890d +Subproject commit 8c14e75011397cd6d16c1182f3377678c885b87a