Skip to content

Commit 6fcc1d8

Browse files
MAfarragMAfarrag
authored
docs: add MkDocs documentation site and rename org to serapeum-org (#2)
 - Add MkDocs configuration and deploy workflow for GitHub Pages - Add documentation pages for all actions (getting-started, python-setup, mkdocs-deploy, release) with usage guides, examples, and API reference - Add generate_action_docs.py script for auto-generating reference docs - Improve input parameter descriptions with examples across all composite actions (pip, uv, pixi, mkdocs-deploy) - Rename GitHub organization from Serapieum-of-alex to serapeum-org in all action references, docs, README, and mkdocs.yml - Add .gitignore
1 parent cd02ddb commit 6fcc1d8

32 files changed

Lines changed: 1572 additions & 278 deletions

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

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- 'docs/**'
8+
- 'mkdocs.yml'
9+
- 'actions/**/action.yml'
10+
- 'scripts/generate_action_docs.py'
11+
workflow_dispatch:
12+
13+
permissions:
14+
contents: write
15+
pages: write
16+
17+
jobs:
18+
docs:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- uses: actions/checkout@v5
22+
with:
23+
fetch-depth: 0
24+
25+
- uses: actions/setup-python@v6
26+
with:
27+
python-version: '3.12'
28+
29+
- name: Install documentation dependencies
30+
run: |
31+
pip install mkdocs mkdocs-material pymdown-extensions mike
32+
33+
- name: Generate action reference pages
34+
run: python scripts/generate_action_docs.py
35+
36+
- name: Configure Git
37+
run: |
38+
git config --global user.name '${{ github.actor }}'
39+
git config --global user.email '${{ github.actor }}@users.noreply.github.com'
40+
41+
- name: Deploy with mike
42+
run: |
43+
mike deploy --push --update-aliases main latest
44+
mike set-default --push latest

‎.github/workflows/test-mkdocs-deploy.yml‎

Lines changed: 33 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,9 @@ jobs:
1919
with:
2020
fetch-depth: 0
2121

22+
- name: Setup fake git remote for testing
23+
uses: ./.github/workflows/test-helpers/setup-fake-remote
24+
2225
- name: Copy test fixture files (pip/uv)
2326
if: matrix.package-manager != 'pixi'
2427
run: |
@@ -50,9 +53,6 @@ jobs:
5053
echo "groups=groups: docs" >> $GITHUB_OUTPUT
5154
fi
5255
53-
- name: Setup fake git remote for testing
54-
uses: ./.github/workflows/test-helpers/setup-fake-remote
55-
5656
- name: Test MkDocs deploy for PR
5757
uses: ./actions/mkdocs-deploy
5858
with:
@@ -73,16 +73,16 @@ jobs:
7373
with:
7474
fetch-depth: 0
7575

76+
- name: Setup fake git remote for testing
77+
uses: ./.github/workflows/test-helpers/setup-fake-remote
78+
7679
- name: Copy test fixture files
7780
run: |
7881
cp tests/data/mkdocs-deploy/test-main-trigger/pyproject.toml .
7982
cp tests/data/mkdocs-deploy/test-main-trigger/uv.lock .
8083
cp tests/data/mkdocs-deploy/test-main-trigger/mkdocs.yml .
8184
cp -r tests/data/mkdocs-deploy/test-main-trigger/docs .
8285
83-
- name: Setup fake git remote for testing
84-
uses: ./.github/workflows/test-helpers/setup-fake-remote
85-
8686
- name: Test MkDocs deploy for main
8787
uses: ./actions/mkdocs-deploy
8888
with:
@@ -110,6 +110,9 @@ jobs:
110110
with:
111111
fetch-depth: 0
112112

113+
- name: Setup fake git remote for testing
114+
uses: ./.github/workflows/test-helpers/setup-fake-remote
115+
113116
- name: Copy test fixture files (pip/uv)
114117
if: matrix.package-manager != 'pixi'
115118
run: |
@@ -140,9 +143,6 @@ jobs:
140143
echo "groups=groups: docs" >> $GITHUB_OUTPUT
141144
fi
142145
143-
- name: Setup fake git remote for testing
144-
uses: ./.github/workflows/test-helpers/setup-fake-remote
145-
146146
- name: Test MkDocs deploy for release
147147
uses: ./actions/mkdocs-deploy
148148
with:
@@ -181,16 +181,16 @@ jobs:
181181
with:
182182
fetch-depth: 0
183183

184+
- name: Setup fake git remote for testing
185+
uses: ./.github/workflows/test-helpers/setup-fake-remote
186+
184187
- name: Copy test fixture files
185188
run: |
186189
cp tests/data/mkdocs-deploy/test-custom-configuration/pyproject.toml .
187190
cp tests/data/mkdocs-deploy/test-custom-configuration/mkdocs.yml .
188191
cp tests/data/mkdocs-deploy/test-custom-configuration/uv.lock .
189192
cp -r tests/data/mkdocs-deploy/test-custom-configuration/docs .
190193
191-
- name: Setup fake git remote for testing
192-
uses: ./.github/workflows/test-helpers/setup-fake-remote
193-
194194
- name: Test with custom configuration
195195
uses: ./actions/mkdocs-deploy
196196
with:
@@ -266,6 +266,9 @@ jobs:
266266
with:
267267
fetch-depth: 0
268268

269+
- name: Setup fake git remote for testing
270+
uses: ./.github/workflows/test-helpers/setup-fake-remote
271+
269272
- name: Copy test fixture files
270273
run: |
271274
cp tests/data/mkdocs-deploy/test-git-configuration/pyproject.toml .
@@ -277,9 +280,6 @@ jobs:
277280
git config --global --unset user.name || true
278281
git config --global --unset user.email || true
279282
280-
- name: Setup fake git remote for testing
281-
uses: ./.github/workflows/test-helpers/setup-fake-remote
282-
283283
- name: Test git configuration
284284
uses: ./actions/mkdocs-deploy
285285
with:
@@ -300,6 +300,9 @@ jobs:
300300
with:
301301
fetch-depth: 0
302302

303+
- name: Setup fake git remote for testing
304+
uses: ./.github/workflows/test-helpers/setup-fake-remote
305+
303306
- name: Copy test fixture files
304307
run: |
305308
cp tests/data/mkdocs-deploy/test-package-manager-commands/pyproject.toml .
@@ -314,9 +317,6 @@ jobs:
314317
cp tests/data/mkdocs-deploy/test-package-manager-commands/pixi.lock .
315318
fi
316319
317-
- name: Setup fake git remote for testing
318-
uses: ./.github/workflows/test-helpers/setup-fake-remote
319-
320320
- name: Test pip command execution
321321
uses: ./actions/mkdocs-deploy
322322
with:
@@ -348,16 +348,16 @@ jobs:
348348
with:
349349
fetch-depth: 0
350350

351+
- name: Setup fake git remote for testing
352+
uses: ./.github/workflows/test-helpers/setup-fake-remote
353+
351354
- name: Copy test fixture files
352355
run: |
353356
cp tests/data/mkdocs-deploy/test-release-tag-resolution/pyproject.toml .
354357
cp tests/data/mkdocs-deploy/test-release-tag-resolution/mkdocs.yml .
355358
cp tests/data/mkdocs-deploy/test-release-tag-resolution/uv.lock .
356359
cp -r tests/data/mkdocs-deploy/test-release-tag-resolution/docs .
357360
358-
- name: Setup fake git remote for testing
359-
uses: ./.github/workflows/test-helpers/setup-fake-remote
360-
361361
- name: Test with explicit release tag
362362
uses: ./actions/mkdocs-deploy
363363
with:
@@ -386,6 +386,9 @@ jobs:
386386
with:
387387
fetch-depth: 0
388388

389+
- name: Setup fake git remote for testing
390+
uses: ./.github/workflows/test-helpers/setup-fake-remote
391+
389392
- name: Copy test fixture files (pip/uv)
390393
if: matrix.package-manager != 'pixi'
391394
run: |
@@ -413,9 +416,6 @@ jobs:
413416
echo "groups=groups: docs" >> $GITHUB_OUTPUT
414417
fi
415418
416-
- name: Setup fake git remote for testing
417-
uses: ./.github/workflows/test-helpers/setup-fake-remote
418-
419419
- name: Test with default install-groups (groups docs)
420420
uses: ./actions/mkdocs-deploy
421421
with:
@@ -440,6 +440,9 @@ jobs:
440440
with:
441441
fetch-depth: 0
442442

443+
- name: Setup fake git remote for testing
444+
uses: ./.github/workflows/test-helpers/setup-fake-remote
445+
443446
- name: Copy test fixture files
444447
run: |
445448
cp tests/data/mkdocs-deploy/test-pull-request-pixi/pyproject.toml .
@@ -449,9 +452,6 @@ jobs:
449452
cp tests/data/mkdocs-deploy/test-pull-request-pixi/pixi.lock .
450453
fi
451454
452-
- name: Setup fake git remote for testing
453-
uses: ./.github/workflows/test-helpers/setup-fake-remote
454-
455455
- name: Test pixi with environment "${{ matrix.install-groups }}"
456456
uses: ./actions/mkdocs-deploy
457457
with:
@@ -476,16 +476,16 @@ jobs:
476476
with:
477477
fetch-depth: 0
478478

479+
- name: Setup fake git remote for testing
480+
uses: ./.github/workflows/test-helpers/setup-fake-remote
481+
479482
- name: Copy test fixture files
480483
run: |
481484
cp tests/data/mkdocs-deploy/test-custom-configuration/pyproject.toml .
482485
cp tests/data/mkdocs-deploy/test-custom-configuration/mkdocs.yml .
483486
cp tests/data/mkdocs-deploy/test-custom-configuration/uv.lock .
484487
cp -r tests/data/mkdocs-deploy/test-custom-configuration/docs .
485488
486-
- name: Setup fake git remote for testing
487-
uses: ./.github/workflows/test-helpers/setup-fake-remote
488-
489489
- name: Test install-groups format "${{ matrix.install-groups }}"
490490
uses: ./actions/mkdocs-deploy
491491
with:
@@ -525,16 +525,16 @@ jobs:
525525
with:
526526
fetch-depth: 0
527527

528+
- name: Setup fake git remote for testing
529+
uses: ./.github/workflows/test-helpers/setup-fake-remote
530+
528531
- name: Copy test fixture files
529532
run: |
530533
cp tests/data/mkdocs-deploy/test-custom-configuration/pyproject.toml .
531534
cp tests/data/mkdocs-deploy/test-custom-configuration/mkdocs.yml .
532535
cp tests/data/mkdocs-deploy/test-custom-configuration/uv.lock .
533536
cp -r tests/data/mkdocs-deploy/test-custom-configuration/docs .
534537
535-
- name: Setup fake git remote for testing
536-
uses: ./.github/workflows/test-helpers/setup-fake-remote
537-
538538
- name: Test install-groups format "${{ matrix.install-groups }}"
539539
uses: ./actions/mkdocs-deploy
540540
with:

‎.gitignore‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# MkDocs build output
2+
site/
3+
4+
# Python
5+
__pycache__/
6+
*.pyc
7+
8+
# IDE
9+
.idea/
10+
.vscode/
11+
*.swp

‎README.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Serapeum GitHub Actions
2+
3+
[![Test pip](https://github.com/serapeum-org/github-actions/actions/workflows/test-python-setup-pip.yml/badge.svg)](https://github.com/serapeum-org/github-actions/actions/workflows/test-python-setup-pip.yml)
4+
[![Test uv](https://github.com/serapeum-org/github-actions/actions/workflows/test-python-setup-uv.yml/badge.svg)](https://github.com/serapeum-org/github-actions/actions/workflows/test-python-setup-uv.yml)
5+
[![Test pixi](https://github.com/serapeum-org/github-actions/actions/workflows/test-python-setup-pixi.yml/badge.svg)](https://github.com/serapeum-org/github-actions/actions/workflows/test-python-setup-pixi.yml)
6+
7+
Reusable composite GitHub Actions for Python CI/CD workflows. Cross-platform (Windows, macOS, Linux), supporting pip, uv, and pixi package managers.
8+
9+
## Actions
10+
11+
### Python Setup
12+
13+
Set up Python with your preferred package manager, install dependencies, and configure caching.
14+
15+
| Action | Usage |
16+
|--------|-------|
17+
| **[pip](docs/python-setup/pip.md)** | `serapeum-org/github-actions/actions/python-setup/pip@pip/v1` |
18+
| **[uv](docs/python-setup/uv.md)** | `serapeum-org/github-actions/actions/python-setup/uv@uv/v1` |
19+
| **[pixi](docs/python-setup/pixi.md)** | `serapeum-org/github-actions/actions/python-setup/pixi@pixi/v1` |
20+
21+
### Documentation
22+
23+
| Action | Usage |
24+
|--------|-------|
25+
| **[mkdocs-deploy](docs/mkdocs-deploy.md)** | `serapeum-org/github-actions/actions/mkdocs-deploy@mkdocs-deploy/v1` |
26+
27+
### Release
28+
29+
| Action | Usage |
30+
|--------|-------|
31+
| **[GitHub Release](docs/release/github/README.md)** | `serapeum-org/github-actions/actions/release/github@release-github/v1` |
32+
| **[PyPI Release](docs/release/pypi/README.md)** | `serapeum-org/github-actions/actions/release/pypi@release-pypi/v1` |
33+
34+
## Quick Start
35+
36+
```yaml
37+
name: CI
38+
39+
on: [push, pull_request]
40+
41+
jobs:
42+
test:
43+
runs-on: ubuntu-latest
44+
steps:
45+
- uses: actions/checkout@v5
46+
47+
- uses: serapeum-org/github-actions/actions/python-setup/uv@uv/v1
48+
with:
49+
python-version: '3.12'
50+
install-groups: 'groups: dev test'
51+
52+
- run: pytest
53+
```
54+
55+
## Dependency Groups Format
56+
57+
The `install-groups` input (for pip and uv) supports:
58+
59+
```yaml
60+
# PEP 735 dependency groups
61+
install-groups: 'groups: dev test'
62+
63+
# Optional dependencies (extras)
64+
install-groups: 'extras: aws viz'
65+
66+
# Both combined
67+
install-groups: 'groups: dev, extras: aws'
68+
```
69+
70+
For pixi, use the `environments` input instead:
71+
72+
```yaml
73+
environments: 'default py312'
74+
```
75+
76+
## Versioning
77+
78+
Each action is versioned independently with namespaced tags:
79+
80+
```
81+
pip/v1.0.0 pip/v1 # Python setup with pip
82+
uv/v1.2.0 uv/v1 # Python setup with uv
83+
pixi/v1.0.0 pixi/v1 # Python setup with pixi
84+
```
85+
86+
Pin to a major version tag for automatic patch/minor updates:
87+
88+
```yaml
89+
uses: serapeum-org/github-actions/actions/python-setup/uv@uv/v1
90+
```
91+
92+
See the [Versioning Guide](docs/VERSIONING.md) for details.
93+
94+
## Documentation
95+
96+
Full documentation is available at the [docs site](https://serapeum-org.github.io/github-actions/) or browse the `docs/` directory.
97+
98+
## Contributing
99+
100+
1. Read the test workflows in `.github/workflows/test-*.yml`
101+
2. Use test fixtures from `tests/data/`
102+
3. Maintain cross-platform compatibility (`shell: bash`)
103+
4. Follow [semantic versioning](docs/VERSIONING.md)
104+
105+
## License
106+
107+
See [LICENSE](LICENSE) for details.

0 commit comments

Comments
 (0)