Skip to content

Commit b112a4a

Browse files
tonytony
authored
Bootstrap gp-sphinx project skeleton (#1)
## Summary - Bootstrap full project skeleton for `gp-sphinx`, the shared Sphinx documentation platform for git-pull projects - Consolidates duplicated docs infrastructure from 14+ repositories into a single reusable package ### Source package (`src/gp_sphinx/`) - `config.py` — `merge_sphinx_config()` API: builds complete Sphinx conf namespace from shared defaults with per-project overrides - `defaults.py` — Single source of truth for 14 shared extensions, Furo theme options, MyST config, IBM Plex font config, sidebar layout, copybutton/autodoc settings - `sphinx_fonts.py` — Bundled Fontsource CDN font extension (was duplicated as `docs/_ext/sphinx_fonts.py` across all repos) - `assets/spa-nav.js` — SPA navigation workaround (also previously duplicated) ### Tooling & CI - `pyproject.toml` — hatchling build, src layout, uv, ruff, mypy strict, pytest with `--doctest-modules` - `justfile` + `docs/justfile` — Task runner (test, lint, format, docs groups) - `.tmuxp.yaml` — Dev session with watch-mypy, watch-test, sphinx-autobuild - `.github/workflows/tests.yml` — Python 3.10–3.14 matrix, ruff, mypy, pytest, codecov, PyPI Trusted Publisher release - `.github/workflows/docs.yml` — S3/CloudFront/Cloudflare deployment ### Documentation - `docs/conf.py` — Dogfoods `gp_sphinx` itself via `merge_sphinx_config()` - Quickstart with before/after `conf.py` examples - `docs/project/` — Contributing, code style, releasing guides - Shared templates (page.html, sidebar/brand.html, sidebar/projects.html) and custom.css from gp-libs
2 parents c213079 + 9b9234b commit b112a4a

39 files changed

+4829
-0
lines changed

‎.github/contributing.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Contributing
2+
3+
When contributing to this repository, please first discuss the change you wish to make via issue,
4+
email, or any other method with the maintainers of this repository before making a change.
5+
6+
See [developing](../docs/developing.md) for environment setup and [AGENTS.md](../AGENTS.md) for
7+
detailed coding standards.
8+
9+
## Pull Request Process
10+
11+
1. **Format and lint**: `uv run ruff format .` then `uv run ruff check . --fix --show-fixes`
12+
2. **Type check**: `uv run mypy`
13+
3. **Test**: `uv run pytest` — all tests must pass before submitting
14+
4. **Document**: Update docs if your change affects the public interface
15+
5. You may merge the Pull Request once you have the sign-off of one other developer. If you
16+
do not have permission to do that, you may request a reviewer to merge it for you.
17+
18+
## Decorum
19+
20+
- Participants will be tolerant of opposing views.
21+
- Participants must ensure that their language and actions are free of personal
22+
attacks and disparaging personal remarks.
23+
- When interpreting the words and actions of others, participants should always
24+
assume good intentions.
25+
- Behaviour which can be reasonably considered harassment will not be tolerated.
26+
27+
Based on [Ruby's Community Conduct Guideline](https://www.ruby-lang.org/en/conduct/)

‎.github/dependabot.yml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
version: 2
2+
updates:
3+
- package-ecosystem: "github-actions"
4+
directory: "/"
5+
schedule:
6+
# Check for updates to GitHub Actions every week
7+
interval: "weekly"

‎.github/workflows/docs.yml‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
name: docs
2+
3+
on:
4+
push:
5+
branches:
6+
- master
7+
- init
8+
9+
permissions:
10+
contents: read
11+
id-token: write
12+
13+
jobs:
14+
build:
15+
runs-on: ubuntu-latest
16+
environment: docs
17+
strategy:
18+
matrix:
19+
python-version: ['3.14']
20+
steps:
21+
- uses: actions/checkout@v6
22+
23+
- name: Filter changed file paths to outputs
24+
uses: dorny/[email protected]
25+
id: changes
26+
with:
27+
filters: |
28+
root_docs:
29+
- CHANGES
30+
- README.*
31+
docs:
32+
- 'docs/**'
33+
- 'examples/**'
34+
python_files:
35+
- 'src/gp_sphinx/**/*.py'
36+
- pyproject.toml
37+
- uv.lock
38+
39+
- name: Should publish
40+
# if: steps.changes.outputs.docs == 'true' || steps.changes.outputs.root_docs == 'true' || steps.changes.outputs.python_files == 'true'
41+
run: echo "PUBLISH=$(echo true)" >> $GITHUB_ENV
42+
43+
- name: Install uv
44+
uses: astral-sh/setup-uv@v7
45+
if: env.PUBLISH == 'true'
46+
with:
47+
enable-cache: true
48+
49+
- name: Set up Python ${{ matrix.python-version }}
50+
if: env.PUBLISH == 'true'
51+
run: uv python install ${{ matrix.python-version }}
52+
53+
- name: Install dependencies
54+
if: env.PUBLISH == 'true'
55+
run: uv sync --all-extras --dev
56+
57+
- name: Install just
58+
if: env.PUBLISH == 'true'
59+
uses: extractions/setup-just@v3
60+
61+
- name: Print python versions
62+
if: env.PUBLISH == 'true'
63+
run: |
64+
python -V
65+
uv run python -V
66+
67+
- name: Cache sphinx fonts
68+
if: env.PUBLISH == 'true'
69+
uses: actions/cache@v5
70+
with:
71+
path: ~/.cache/sphinx-fonts
72+
key: sphinx-fonts-${{ hashFiles('docs/conf.py') }}
73+
restore-keys: |
74+
sphinx-fonts-
75+
76+
- name: Build documentation
77+
if: env.PUBLISH == 'true'
78+
run: |
79+
cd docs && just html
80+
81+
- name: Configure AWS Credentials
82+
if: env.PUBLISH == 'true'
83+
uses: aws-actions/configure-aws-credentials@v5
84+
with:
85+
role-to-assume: ${{ secrets.GP_SPHINX_DOCS_ROLE_ARN }}
86+
aws-region: us-east-1
87+
88+
- name: Push documentation to S3
89+
if: env.PUBLISH == 'true'
90+
run: |
91+
aws s3 sync docs/_build/html "s3://${{ secrets.GP_SPHINX_DOCS_BUCKET }}" \
92+
--delete --follow-symlinks
93+
94+
- name: Invalidate CloudFront
95+
if: env.PUBLISH == 'true'
96+
run: |
97+
aws cloudfront create-invalidation \
98+
--distribution-id "${{ secrets.GP_SPHINX_DOCS_DISTRIBUTION }}" \
99+
--paths "/index.html" "/objects.inv" "/searchindex.js"
100+
101+
- name: Purge cache on Cloudflare
102+
if: env.PUBLISH == 'true'
103+
uses: jakejarvis/[email protected]
104+
env:
105+
CLOUDFLARE_TOKEN: ${{ secrets.CLOUDFLARE_TOKEN }}
106+
CLOUDFLARE_ZONE: ${{ secrets.CLOUDFLARE_ZONE }}

‎.github/workflows/tests.yml‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
name: tests
2+
3+
on: [push, pull_request]
4+
5+
jobs:
6+
build:
7+
if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
8+
9+
runs-on: ubuntu-latest
10+
strategy:
11+
matrix:
12+
python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
13+
steps:
14+
- uses: actions/checkout@v6
15+
16+
- name: Install uv
17+
uses: astral-sh/setup-uv@v7
18+
with:
19+
enable-cache: true
20+
21+
- name: Set up Python ${{ matrix.python-version }}
22+
run: uv python install ${{ matrix.python-version }}
23+
24+
- name: Install dependencies
25+
run: uv sync --all-extras --dev
26+
27+
- name: Print python and pytest versions
28+
run: |
29+
python -V
30+
uv run python -V
31+
uv run pytest --version
32+
33+
- name: Lint with ruff check
34+
run: uv run ruff check .
35+
36+
- name: Format with ruff format
37+
run: uv run ruff format . --check
38+
39+
- name: Lint with mypy
40+
run: uv run mypy .
41+
42+
- name: Test with pytest
43+
run: uv run py.test --cov=./ --cov-report=xml
44+
45+
- uses: codecov/codecov-action@v5
46+
with:
47+
token: ${{ secrets.CODECOV_TOKEN }}
48+
49+
release:
50+
runs-on: ubuntu-latest
51+
needs: build
52+
if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
53+
permissions:
54+
id-token: write
55+
attestations: write
56+
57+
strategy:
58+
matrix:
59+
python-version: ['3.14']
60+
61+
steps:
62+
- uses: actions/checkout@v6
63+
64+
- name: Install uv
65+
uses: astral-sh/setup-uv@v7
66+
with:
67+
enable-cache: true
68+
69+
- name: Set up Python ${{ matrix.python-version }}
70+
run: uv python install ${{ matrix.python-version }}
71+
72+
- name: Install dependencies
73+
run: uv sync --all-extras --dev
74+
75+
- name: Build package
76+
if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
77+
run: uv build
78+
79+
- name: Publish package
80+
if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
81+
uses: pypa/gh-action-pypi-publish@release/v1
82+
with:
83+
attestations: true
84+
skip-existing: true

‎.gitignore‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -205,3 +205,18 @@ cython_debug/
205205
marimo/_static/
206206
marimo/_lsp/
207207
__marimo__/
208+
209+
# Generated by sphinx_fonts extension (downloaded at build time)
210+
docs/_static/fonts/
211+
docs/_static/css/fonts.css
212+
213+
# Claude Code
214+
**/CLAUDE.local.md
215+
**/CLAUDE.*.md
216+
**/.claude/settings.local.json
217+
218+
# Misc
219+
.vim/
220+
*.lprof
221+
pip-wheel-metadata/
222+
monkeytype.sqlite3

‎.python-version‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
3.14

‎.tmuxp.yaml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
session_name: gp-sphinx
2+
start_directory: ./ # load session relative to config location (project root).
3+
shell_command_before:
4+
- uv virtualenv --quiet > /dev/null 2>&1 && clear
5+
windows:
6+
- window_name: gp-sphinx
7+
focus: True
8+
layout: main-horizontal
9+
options:
10+
main-pane-height: 67%
11+
panes:
12+
- focus: true
13+
- pane
14+
- just watch-mypy
15+
- just watch-test
16+
- window_name: docs
17+
layout: main-horizontal
18+
options:
19+
main-pane-height: 67%
20+
start_directory: docs/
21+
panes:
22+
- focus: true
23+
- pane
24+
- pane
25+
- just start

‎.tool-versions‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
just 1.47
2+
uv 0.11.2
3+
python 3.14 3.13 3.12 3.11 3.10

‎CHANGES‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Changelog
2+
3+
To install the unreleased gp-sphinx version, see [developmental releases](https://gp-sphinx.git-pull.com/quickstart.html#developmental-releases).
4+
5+
[pip](https://pip.pypa.io/en/stable/):
6+
7+
```console
8+
$ pip install --user --upgrade --pre gp-sphinx
9+
```
10+
11+
[uv](https://docs.astral.sh/uv/):
12+
13+
```console
14+
$ uv add gp-sphinx --prerelease allow
15+
```
16+
17+
## gp-sphinx 0.0.1 (unreleased)
18+
19+
<!-- To maintainers and contributors: Please add notes for the forthcoming version below -->
20+
21+
### Features
22+
23+
- Initial release of `gp_sphinx` shared documentation platform
24+
- `merge_sphinx_config()` API for building complete Sphinx config from shared defaults
25+
- Shared extension list, theme options, MyST config, font config
26+
- Bundled workarounds (tabs.js removal, spa-nav.js injection)

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
AGENTS.md

0 commit comments

Comments
 (0)