Skip to content

Commit 4ab1c1d

Browse files
ByteOtterByteOtter
authored
Merge pull request #344 from gardenlinux/docs-ng
[Docs] Restructure Documentaion to Diataxes structure based on work for `docs-ng`
2 parents acc50b5 + 596d152 commit 4ab1c1d

16 files changed

Lines changed: 352 additions & 58 deletions

File tree

‎.github/workflows/docs-check.yml‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
name: Documentation Quality Check
2+
3+
on:
4+
pull_request:
5+
branches: [main, docs-ng]
6+
types: [opened, synchronize, reopened, closed]
7+
paths:
8+
- 'docs/**'
9+
push:
10+
branches: [main, docs-ng]
11+
paths:
12+
- 'docs/**'
13+
14+
jobs:
15+
docs-checks:
16+
# Skip checks on closed PRs (only need the notification)
17+
if: github.event_name != 'pull_request' || github.event.action != 'closed'
18+
uses: gardenlinux/docs-ng/.github/workflows/docs-checks.yml@main
19+
with:
20+
override-repo: ${{ github.event.repository.name }}
21+
override-ref: ${{ github.head_ref || github.ref_name }}
22+
override-commit: ${{ github.event.pull_request.head.sha || github.sha }}
23+
24+
notify-docs-ng:
25+
name: Notify docs-ng
26+
needs: [docs-checks]
27+
runs-on: ubuntu-24.04
28+
# Only notify for PR events (not push events which lack PR context)
29+
# Run after checks pass for open PRs, OR immediately for merged PRs
30+
if: |
31+
always() &&
32+
github.event_name == 'pull_request' &&
33+
(
34+
(github.event.action == 'closed' && github.event.pull_request.merged == true) ||
35+
(github.event.action != 'closed' && needs.docs-checks.result == 'success')
36+
)
37+
steps:
38+
- name: Generate GitHub App token
39+
id: app-token
40+
uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
41+
with:
42+
app-id: ${{ secrets.DOCS_BOT_APP_ID }}
43+
private-key: ${{ secrets.DOCS_BOT_PRIVATE_KEY }}
44+
repositories: docs-ng
45+
46+
- name: Send repository dispatch to docs-ng
47+
uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
48+
with:
49+
github-token: ${{ steps.app-token.outputs.token }}
50+
script: |
51+
const isMergedPR = context.payload.action === 'closed' &&
52+
context.payload.pull_request.merged === true;
53+
54+
// For merged PRs, use the base branch (the branch it was merged into)
55+
// For open PRs, use the head branch (feature branch)
56+
const ref = isMergedPR
57+
? context.payload.pull_request.base.ref
58+
: context.payload.pull_request.head.ref;
59+
60+
await github.rest.repos.createDispatchEvent({
61+
owner: 'gardenlinux',
62+
repo: 'docs-ng',
63+
event_type: 'docs-pr',
64+
client_payload: {
65+
repo: '${{ github.event.repository.name }}',
66+
pr_number: `${context.payload.pull_request.number}`,
67+
commit_sha: isMergedPR
68+
? context.payload.pull_request.merge_commit_sha
69+
: context.payload.pull_request.head.sha,
70+
ref: ref,
71+
event: isMergedPR ? 'merged' : 'pr_success'
72+
}
73+
});
74+
core.info('Repository dispatch sent to docs-ng');

‎README.md‎

Lines changed: 34 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,17 @@
1+
## Garden Linux Python Library
2+
13
![poetry build](https://github.com/gardenlinux/parse_features_lib/actions/workflows/build.yml/badge.svg)
24
![Black Lint](https://github.com/gardenlinux/parse_features_lib/actions/workflows/black.yml/badge.svg)
35
![Test](https://github.com/gardenlinux/parse_features_lib/actions/workflows/pytests.yml/badge.svg)
46
![security check](https://github.com/gardenlinux/parse_features_lib/actions/workflows/bandit.yml/badge.svg)
57

6-
## Garden Linux Python Library
7-
8-
Python tooling to work with [Garden Linux](https://github.com/gardenlinux/gardenlinux) features, flavors, OCI artifacts, repositories, and releases.
9-
It is primarily targeted at Garden Linux developers and CI pipelines rather than end users.
8+
Python tooling to work with
9+
[Garden Linux](https://github.com/gardenlinux/gardenlinux) features, flavors,
10+
OCI artifacts, repositories, and releases. It is primarily targeted at Garden
11+
Linux developers and CI pipelines rather than end users.
1012

11-
The library follows the intent of [Semantic Versioning](https://semver.org) for its public APIs.
13+
The library follows the intent of [Semantic Versioning](https://semver.org) for
14+
its public APIs.
1215

1316
### Features
1417

@@ -21,59 +24,45 @@ The library follows the intent of [Semantic Versioning](https://semver.org) for
2124

2225
## Documentation
2326

24-
Full documentation is available at the **Garden Linux Python Library Documentation** site:
25-
[https://gardenlinux.github.io/python-gardenlinux-lib/](https://gardenlinux.github.io/python-gardenlinux-lib/)
26-
27-
The docs include:
28-
29-
- **Command-Line Interface**: `gl-features-*`, `gl-flavors-*`, `gl-oci`, `gl-s3`, `gl-gh-release`
30-
- **API Reference**: modules, classes, and functions (e.g. `Parser`, `CName`, `Container`, `Repository`)
31-
- **Release documentation**: versioning and release process
32-
33-
## Installation
27+
You can find a full documentation about how to
28+
[install this python library](https://gardenlinux-docs.netlify.app/reference/supporting_tools/python-gardenlinux-lib.html#installation)
29+
and
30+
[use its CLI interface](https://gardenlinux-docs.netlify.app/reference/python-gardenlinux-lib-cli.html)
31+
this on our [documentation hub](https://gardenlinux-docs.netlify.app/).
3432

35-
### Using `poetry` (from Git)
33+
For a detailed API documentation, check
34+
[gardenlinux.github.io/python-gardenlinux-lib/api.html](https://gardenlinux.github.io/python-gardenlinux-lib/)
3635

37-
Add the library as a dependency in your `pyproject.toml`:
36+
# Community
3837

39-
```toml
40-
[tool.poetry.dependencies]
41-
gardenlinux = { git = "https://github.com/gardenlinux/python-gardenlinux-lib", rev = "0.10.5" }
42-
```
38+
To stay up-to-date with recent news about Gardenlinux, subscribe to our mailing
39+
list:
4340

44-
Then install:
41+
https://lists.neonephos.org/g/gardenlinux-discussion
4542

46-
```bash
47-
poetry install
48-
```
43+
For updates and statements regarding security issues, we have a security mailing
44+
list for you:
4945

50-
### Local development setup
46+
https://lists.neonephos.org/g/gardenlinux-security
5147

52-
```bash
53-
git clone https://github.com/gardenlinux/python-gardenlinux-lib.git
54-
cd python-gardenlinux-lib
55-
python -m venv venv
56-
source venv/bin/activate
57-
poetry install
58-
```
48+
For embargoed security related topics, this list is for you:
5949

60-
## Quickstart
50+
https://lists.neonephos.org/g/gardenlinux-security-embargo
6151

62-
### Example: list features for a given `cname`
52+
# Contributing
6353

64-
```python
65-
from gardenlinux.features import Parser
54+
We welcome your contributions to Gardenlinux or any supporting projects.
6655

67-
cname = "aws-gardener_prod"
68-
feature_list = Parser().filter_as_list(cname)
56+
To find our more, visit our
57+
[Contributor Documentation](https://gardenlinux-docs.netlify.app/contributing).
6958

70-
print(f"features of {cname}:")
71-
for feature in feature_list:
72-
print(feature)
73-
```
59+
## Licensing
7460

75-
For more examples and for all CLI tools, see the **Command-Line Interface** and **API Reference** sections in the docs:
76-
[https://gardenlinux.github.io/python-gardenlinux-lib/](https://gardenlinux.github.io/python-gardenlinux-lib/)
61+
Copyright 2025 SAP SE or an SAP affiliate company and GardenLinux contributors.
62+
See our [LICENSE](LICENSE.md) for copyright and license information.
63+
Detailed information including third-party components and their
64+
licensing/copyright information is available
65+
[via the REUSE tool](https://reuse.software).
7766

7867
<p align="center">
7968
<img alt="Bundesministerium für Wirtschaft und Energie (BMWE)-EU funding logo" src="https://apeirora.eu/assets/img/BMWK-EU.png" width="400"/>

‎docs/Makefile‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,11 @@ BUILDDIR = _build
1212
help:
1313
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
1414

15-
.PHONY: help Makefile
15+
.PHONY: help markdown Makefile
16+
17+
# Explicit markdown target: build Markdown output via sphinx-markdown-builder
18+
markdown:
19+
@$(SPHINXBUILD) -M markdown "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
1620

1721
# Catch-all target: route all unknown targets to Sphinx using the new
1822
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).

‎docs/api.rst‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,34 @@
1-
API Reference
2-
=============
1+
Python Library - API Reference
2+
==============================
33

4-
This section provides detailed documentation for all Python modules and classes in python-gardenlinux-lib.
4+
Detailed documentation for all Python modules and classes in the Garden Linux Python Library
55

6-
.. automodule:: gardenlinux
7-
:members:
6+
gardenlinux.apt
7+
~~~~~~~~~~~~~~~
88

99
.. automodule:: gardenlinux.apt
1010
:members:
1111

12+
gardenlinux.features
13+
~~~~~~~~~~~~~~~~~~~~
14+
1215
.. automodule:: gardenlinux.features
1316
:members:
1417

18+
gardenlinux.flavors
19+
~~~~~~~~~~~~~~~~~~~
20+
1521
.. automodule:: gardenlinux.flavors
1622
:members:
1723

24+
gardenlinux.git
25+
~~~~~~~~~~~~~~~
26+
1827
.. automodule:: gardenlinux.git
1928
:members:
2029

30+
gardenlinux.oci
31+
~~~~~~~~~~~~~~~
32+
2133
.. automodule:: gardenlinux.oci
2234
:members:

‎docs/cli.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
Command-Line Interface
2-
======================
1+
Python Library - Command-Line Interface
2+
=======================================
33

4-
This page documents all available command-line tools provided by python-gardenlinux-lib.
4+
Available command-line tools provided by the Garden Linux Python Library
55

66
Features Commands
77
-----------------

‎docs/conf.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,15 @@
2222
"sphinx.ext.napoleon",
2323
"sphinx_click",
2424
"sphinxcontrib.autoprogram",
25+
"sphinx_markdown_builder",
2526
]
2627

28+
# Markdown builder configuration (GitHub-Flavored Markdown for VitePress)
29+
# We can enable this after https://github.com/liran-funaro/sphinx-markdown-builder/pull/53 is merged
30+
# markdown_flavor = "github"
31+
markdown_anchor_sections = True
32+
markdown_anchor_signatures = True
33+
2734
templates_path = ["_templates"]
2835
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
2936
autodoc_mock_imports = ["networkx"]

‎docs/contributing/.gitkeep‎

Whitespace-only changes.

‎docs/explanation/.gitkeep‎

Whitespace-only changes.

‎docs/how-to/release.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
title: Python Library - Release Process
3+
description: Release a new version of the Garden Linux Python Library
4+
related_topics:
5+
- /reference/supporting_tools/python-gardenlinux-lib
6+
- /reference/python-gardenlinux-lib-cli
7+
- /how-to/python-gardenlinux-lib-release
8+
migration_status: "done"
9+
migration_stakeholder: "@tmangold, @yeoldegrove, @ByteOtter"
10+
migration_approved: false
11+
github_org: gardenlinux
12+
github_repo: python-gardenlinux-lib
13+
github_source_path: docs/how-to/release.md
14+
github_target_path: docs/how-to/python-gardenlinux-lib-release.md
15+
---
16+
17+
# Release Documentation
18+
19+
_python-gardenlinux-lib_ strictly follows the syntax and intention of
20+
[Semantic Versioning](https://www.semver.org). Each release reflects the
21+
intention and expected impact therefore.
22+
23+
A new release is done by tagging a commit with a valid version. This will create
24+
a GitHub pre-release for proof-reading. Once done a new release can be published
25+
using GitHub CLI or UI.
26+
27+
Newly added docstrings should contain the first version supporting the new API /
28+
command line.
29+
30+
## Step by Step Guide
31+
32+
1. **Set version files:**
33+
34+
_python-gardenlinux-lib_ versioning needs to be set in:
35+
- `pyproject.toml`
36+
- `.github/actions/setup/action.yml`
37+
38+
Also at the moment (removal pending):
39+
- `.github/actions/features_parse/action.yml`
40+
- `.github/actions/flavors_parse/action.yml`
41+
42+
2. **Create git tag:**
43+
44+
```bash
45+
git tag <tag>
46+
```
47+
48+
3. **Review and publish:**
49+
50+
Review the generated pre-release changelog by visiting the GitHub project
51+
release page and publish it if applicable.
52+
53+
4. **Consume the library:**
54+
55+
Projects consuming the _python-gardenlinux-lib_ may use the following git URL
56+
for dependency definition:
57+
58+
```bash
59+
pip install git+https://github.com/gardenlinux/python-gardenlinux-lib.git@1.0.0
60+
```
61+
62+
Or in `requirements.txt`:
63+
64+
```
65+
gardenlinux @ git+https://github.com/gardenlinux/python-gardenlinux-lib.git@1.0.0
66+
```
67+
68+
## Related Topics
69+
70+
<RelatedTopics />

‎docs/index.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
Garden Linux Python Library Documentation
1+
Garden Linux Python Library
22
==========================================
33

4-
Welcome to the Garden Linux Python Library documentation. This library provides
4+
The Garden linux Python Library provides
55
Python tools and utilities for working with Garden Linux features, flavors,
66
OCI artifacts, S3 buckets, and GitHub releases.
77

0 commit comments

Comments
 (0)