Skip to content

Commit 262c27b

Browse files
nielsweistranielsweistra
committed
feat: Add documentation for composite actions and reusable workflows
- Create README.md for composite actions detailing usage and overview. - Add detect-release-type.md to document the action for determining release types. - Introduce setup-python-env.md for setting up Python environments in workflows. - Establish getting-started.md to guide users on consuming workflows and actions. - Develop docker-service.md and python-library.md guides for CI/CD setups. - Implement versioning.md to explain versioning strategies for workflows and actions. - Create README.md for reusable workflows with an overview and typical job order. - Document individual workflows: auto-tag.md, ci-docker.md, ci-python.md, detect-version.md, docker-retag.md, publish-pypi.md, and release-gh.md.
1 parent fc75f16 commit 262c27b

20 files changed

Lines changed: 1642 additions & 12 deletions

‎.github/workflows/docs.yml‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
name: Publish Docs
2+
3+
on:
4+
push:
5+
branches: ["main"]
6+
paths:
7+
- "docs/**"
8+
workflow_dispatch:
9+
10+
concurrency:
11+
group: pages
12+
cancel-in-progress: true
13+
14+
env:
15+
FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
16+
17+
permissions:
18+
contents: read
19+
pages: write
20+
id-token: write
21+
22+
jobs:
23+
build:
24+
name: Build Jekyll Site
25+
runs-on: ubuntu-latest
26+
steps:
27+
- name: Checkout
28+
uses: actions/checkout@v4.2.2
29+
30+
- name: Setup Pages
31+
uses: actions/configure-pages@v5.0.0
32+
33+
- name: Build with Jekyll
34+
uses: actions/jekyll-build-pages@v1.0.13
35+
with:
36+
source: ./docs
37+
destination: ./_site
38+
39+
- name: Upload Pages artifact
40+
uses: actions/upload-pages-artifact@v3.0.1
41+
42+
deploy:
43+
name: Deploy to GitHub Pages
44+
runs-on: ubuntu-latest
45+
needs: build
46+
environment:
47+
name: github-pages
48+
url: ${{ steps.deployment.outputs.page_url }}
49+
steps:
50+
- name: Deploy to GitHub Pages
51+
id: deployment
52+
uses: actions/deploy-pages@v4.0.5

‎README.md‎

Lines changed: 18 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -3,28 +3,32 @@
33
Central repository for reusable GitHub Actions workflows and composite actions
44
shared across all ITLusions repositories.
55

6+
**Full documentation:** [docs/README.md](docs/README.md)
7+
68
## Reusable Workflows
79

810
Reference via `uses: ITlusions/ITL.Github/.github/workflows/<name>.yml@main`
911

10-
| Workflow | Description |
11-
|---|---|
12-
| `_reusable-ci-python.yml` | Lint (ruff) + tests + wheel build |
13-
| `_reusable-publish-pypi.yml` | Publish wheel to PyPI via OIDC Trusted Publishing |
14-
| `_reusable-docker-build.yml` | Docker image build + push to registry |
15-
| `_reusable-release-gh.yml` | Create GitHub Release with assets |
16-
| `_reusable-auto-tag.yml` | Semver patch auto-tag on main |
12+
| Workflow | Description | Docs |
13+
|---|---|---|
14+
| `_reusable-detect-version.yml` | Determine semver version from branch/tags | [docs](docs/workflows/detect-version.md) |
15+
| `_reusable-ci-python.yml` | Lint (ruff) + tests + wheel build | [docs](docs/workflows/ci-python.md) |
16+
| `_reusable-ci-docker.yml` | Lint + test + Docker build/push | [docs](docs/workflows/ci-docker.md) |
17+
| `_reusable-auto-tag.yml` | Semver patch auto-tag on main | [docs](docs/workflows/auto-tag.md) |
18+
| `_reusable-docker-retag.yml` | Promote image by retagging (no rebuild) | [docs](docs/workflows/docker-retag.md) |
19+
| `_reusable-publish-pypi.yml` | Publish wheel to PyPI via OIDC | [docs](docs/workflows/publish-pypi.md) |
20+
| `_reusable-release-gh.yml` | Create GitHub Release with assets | [docs](docs/workflows/release-gh.md) |
1721

1822
## Composite Actions
1923

2024
Reference via `uses: ITlusions/ITL.Github/actions/<name>@main`
2125

22-
| Action | Description |
23-
|---|---|
24-
| `setup-python-env` | Python setup + pip install from requirements.txt |
25-
| `detect-release-type` | Detect stable vs pre-release (rc/beta/alpha) |
26+
| Action | Description | Docs |
27+
|---|---|---|
28+
| `setup-python-env` | Python setup + pip install from requirements.txt | [docs](docs/actions/setup-python-env.md) |
29+
| `detect-release-type` | Detect stable vs pre-release (rc/beta/alpha) | [docs](docs/actions/detect-release-type.md) |
2630

27-
## Usage
31+
## Quick Start
2832

2933
```yaml
3034
# Reusable workflow
@@ -41,3 +45,5 @@ steps:
4145
with:
4246
python-version: "3.12"
4347
```
48+
49+
See [Getting Started](docs/getting-started.md) for a full walkthrough.

‎docs/README.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# ITL.Github — Documentation
2+
3+
Central repository for reusable GitHub Actions workflows and composite actions
4+
shared across all ITLusions repositories.
5+
6+
## Navigation
7+
8+
| Section | Description |
9+
|---|---|
10+
| [Getting Started](getting-started.md) | How to consume workflows and actions from another repo |
11+
| [Versioning](versioning.md) | `@main` vs pinned refs, update strategy |
12+
| [Workflows](workflows/README.md) | Reference for all reusable workflows |
13+
| [Actions](actions/README.md) | Reference for all composite actions |
14+
| [Guide: Python Library](guides/python-library.md) | Full CI/CD pipeline for a Python package |
15+
| [Guide: Docker Service](guides/docker-service.md) | Full CI/CD pipeline for a Docker-based service |
16+
17+
## Quick Reference
18+
19+
### Reusable Workflows
20+
21+
```
22+
uses: ITlusions/ITL.Github/.github/workflows/<name>.yml@main
23+
```
24+
25+
| File | Purpose |
26+
|---|---|
27+
| [`_reusable-detect-version.yml`](workflows/detect-version.md) | Determine semver version from branch/tags |
28+
| [`_reusable-ci-python.yml`](workflows/ci-python.md) | Lint + test + wheel build (Python) |
29+
| [`_reusable-ci-docker.yml`](workflows/ci-docker.md) | Lint + test + Docker build/push |
30+
| [`_reusable-auto-tag.yml`](workflows/auto-tag.md) | Push semver patch tag on main |
31+
| [`_reusable-docker-retag.yml`](workflows/docker-retag.md) | Promote image by retagging (no rebuild) |
32+
| [`_reusable-publish-pypi.yml`](workflows/publish-pypi.md) | Publish wheel to PyPI via OIDC |
33+
| [`_reusable-release-gh.yml`](workflows/release-gh.md) | Create GitHub Release with assets |
34+
35+
### Composite Actions
36+
37+
```
38+
uses: ITlusions/ITL.Github/actions/<name>@main
39+
```
40+
41+
| Directory | Purpose |
42+
|---|---|
43+
| [`setup-python-env`](actions/setup-python-env.md) | Python setup + pip install |
44+
| [`detect-release-type`](actions/detect-release-type.md) | Stable vs pre-release detection |

‎docs/_config.yml‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
title: ITL.Github — Shared Actions & Workflows
2+
description: Reusable GitHub Actions workflows and composite actions shared across all ITLusions repositories.
3+
baseurl: "/ITL.Github"
4+
url: "https://itlusions.github.io"
5+
6+
# Build settings
7+
markdown: kramdown
8+
highlighter: rouge
9+
10+
kramdown:
11+
syntax_highlighter: rouge
12+
syntax_highlighter_opts:
13+
block:
14+
line_numbers: false
15+
16+
# Exclude files that shouldn't be built as pages
17+
exclude:
18+
- "*.py"
19+
- "*.sh"
20+
- "docker-compose.yml"
21+
- "Dockerfile"
22+
- "pyproject.toml"
23+
- "README.md"

0 commit comments

Comments
 (0)