Bootstrap gp-sphinx project skeleton

.github/contributing.md

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

.github/dependabot.yml

@@ -0,0 +1,7 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      # Check for updates to GitHub Actions every week
+      interval: "weekly"

.github/workflows/docs.yml

@@ -0,0 +1,106 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - master
+      - init
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    environment: docs
+    strategy:
+      matrix:
+        python-version: ['3.14']
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Filter changed file paths to outputs
+        uses: dorny/paths-filter@v3.0.2
+        id: changes
+        with:
+          filters: |
+            root_docs:
+              - CHANGES
+              - README.*
+            docs:
+              - 'docs/**'
+              - 'examples/**'
+            python_files:
+              - 'src/gp_sphinx/**/*.py'
+              - pyproject.toml
+              - uv.lock
+
+      - name: Should publish
+        # if: steps.changes.outputs.docs == 'true' || steps.changes.outputs.root_docs == 'true' || steps.changes.outputs.python_files == 'true'
+        run: echo "PUBLISH=$(echo true)" >> $GITHUB_ENV
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        if: env.PUBLISH == 'true'
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        if: env.PUBLISH == 'true'
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        if: env.PUBLISH == 'true'
+        run: uv sync --all-extras --dev
+
+      - name: Install just
+        if: env.PUBLISH == 'true'
+        uses: extractions/setup-just@v3
+
+      - name: Print python versions
+        if: env.PUBLISH == 'true'
+        run: |
+          python -V
+          uv run python -V
+
+      - name: Cache sphinx fonts
+        if: env.PUBLISH == 'true'
+        uses: actions/cache@v5
+        with:
+          path: ~/.cache/sphinx-fonts
+          key: sphinx-fonts-${{ hashFiles('docs/conf.py') }}
+          restore-keys: |
+            sphinx-fonts-
+
+      - name: Build documentation
+        if: env.PUBLISH == 'true'
+        run: |
+          cd docs && just html
+
+      - name: Configure AWS Credentials
+        if: env.PUBLISH == 'true'
+        uses: aws-actions/configure-aws-credentials@v5
+        with:
+          role-to-assume: ${{ secrets.GP_SPHINX_DOCS_ROLE_ARN }}
+          aws-region: us-east-1
+
+      - name: Push documentation to S3
+        if: env.PUBLISH == 'true'
+        run: |
+          aws s3 sync docs/_build/html "s3://${{ secrets.GP_SPHINX_DOCS_BUCKET }}" \
+            --delete --follow-symlinks
+
+      - name: Invalidate CloudFront
+        if: env.PUBLISH == 'true'
+        run: |
+          aws cloudfront create-invalidation \
+            --distribution-id "${{ secrets.GP_SPHINX_DOCS_DISTRIBUTION }}" \
+            --paths "/index.html" "/objects.inv" "/searchindex.js"
+
+      - name: Purge cache on Cloudflare
+        if: env.PUBLISH == 'true'
+        uses: jakejarvis/cloudflare-purge-action@v0.3.0
+        env:
+          CLOUDFLARE_TOKEN: ${{ secrets.CLOUDFLARE_TOKEN }}
+          CLOUDFLARE_ZONE: ${{ secrets.CLOUDFLARE_ZONE }}

.github/workflows/tests.yml

@@ -0,0 +1,84 @@
+name: tests
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Print python and pytest versions
+        run: |
+          python -V
+          uv run python -V
+          uv run pytest --version
+
+      - name: Lint with ruff check
+        run: uv run ruff check .
+
+      - name: Format with ruff format
+        run: uv run ruff format . --check
+
+      - name: Lint with mypy
+        run: uv run mypy .
+
+      - name: Test with pytest
+        run: uv run py.test --cov=./ --cov-report=xml
+
+      - uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+  release:
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
+    permissions:
+      id-token: write
+      attestations: write
+
+    strategy:
+      matrix:
+        python-version: ['3.14']
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Build package
+        if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
+        run: uv build
+
+      - name: Publish package
+        if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true
+          skip-existing: true

.gitignore

@@ -205,3 +205,18 @@ cython_debug/
 marimo/_static/
 marimo/_lsp/
 __marimo__/
+
+# Generated by sphinx_fonts extension (downloaded at build time)
+docs/_static/fonts/
+docs/_static/css/fonts.css
+
+# Claude Code
+**/CLAUDE.local.md
+**/CLAUDE.*.md
+**/.claude/settings.local.json
+
+# Misc
+.vim/
+*.lprof
+pip-wheel-metadata/
+monkeytype.sqlite3

.python-version

@@ -0,0 +1 @@
+3.14

.tmuxp.yaml

@@ -0,0 +1,25 @@
+session_name: gp-sphinx
+start_directory: ./ # load session relative to config location (project root).
+shell_command_before:
+- uv virtualenv --quiet > /dev/null 2>&1 && clear
+windows:
+- window_name: gp-sphinx
+  focus: True
+  layout: main-horizontal
+  options:
+    main-pane-height: 67%
+  panes:
+  - focus: true
+  - pane
+  - just watch-mypy
+  - just watch-test
+- window_name: docs
+  layout: main-horizontal
+  options:
+    main-pane-height: 67%
+  start_directory: docs/
+  panes:
+  - focus: true
+  - pane
+  - pane
+  - just start

.tool-versions

@@ -0,0 +1,3 @@
+just 1.47
+uv 0.11.2
+python 3.14 3.13 3.12 3.11 3.10

CHANGES

@@ -0,0 +1,26 @@
+# Changelog
+
+To install the unreleased gp-sphinx version, see [developmental releases](https://gp-sphinx.git-pull.com/quickstart.html#developmental-releases).
+
+[pip](https://pip.pypa.io/en/stable/):
+
+```console
+$ pip install --user --upgrade --pre gp-sphinx
+```
+
+[uv](https://docs.astral.sh/uv/):
+
+```console
+$ uv add gp-sphinx --prerelease allow
+```
+
+## gp-sphinx 0.0.1 (unreleased)
+
+<!-- To maintainers and contributors: Please add notes for the forthcoming version below -->
+
+### Features
+
+- Initial release of `gp_sphinx` shared documentation platform
+- `merge_sphinx_config()` API for building complete Sphinx config from shared defaults
+- Shared extension list, theme options, MyST config, font config
+- Bundled workarounds (tabs.js removal, spa-nav.js injection)

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

README.md

@@ -0,0 +1,56 @@
+# gp-sphinx · [![Python Package](https://img.shields.io/pypi/v/gp-sphinx.svg)](https://pypi.org/project/gp-sphinx/) [![License](https://img.shields.io/github/license/git-pull/gp-sphinx.svg)](https://github.com/git-pull/gp-sphinx/blob/master/LICENSE)
+
+Shared Sphinx documentation platform for [git-pull](https://github.com/git-pull) projects.
+
+Consolidates duplicated docs configuration, extensions, theme settings, and workarounds from 14+ repositories into a single reusable package.
+
+## Install
+
+```console
+$ pip install gp-sphinx
+```
+
+```console
+$ uv add gp-sphinx
+```
+
+## Usage
+
+Replace ~300 lines of duplicated `docs/conf.py` with ~10 lines:
+
+```python
+"""Sphinx configuration for my-project."""
+from __future__ import annotations
+
+from gp_sphinx.config import merge_sphinx_config
+
+import my_project
+
+conf = merge_sphinx_config(
+    project="my-project",
+    version=my_project.__version__,
+    copyright="2026, Tony Narlock",
+    source_repository="https://github.com/git-pull/my-project/",
+    intersphinx_mapping={
+        "py": ("https://docs.python.org/", None),
+    },
+)
+globals().update(conf)
+```
+
+## Features
+
+- `merge_sphinx_config()` API for shared defaults with per-project overrides
+- Shared extension list (autodoc, intersphinx, myst_parser, sphinx_design, etc.)
+- Shared Furo theme configuration (CSS variables, fonts, sidebar, footer)
+- Bundled workarounds (tabs.js removal, spa-nav.js injection)
+- Shared font configuration (IBM Plex via Fontsource)
+
+## More information
+
+- Documentation: <https://gp-sphinx.git-pull.com>
+- Source: <https://github.com/git-pull/gp-sphinx>
+- Changelog: <https://github.com/git-pull/gp-sphinx/blob/master/CHANGES>
+- Issues: <https://github.com/git-pull/gp-sphinx/issues>
+- PyPI: <https://pypi.org/project/gp-sphinx/>
+- License: [MIT](https://github.com/git-pull/gp-sphinx/blob/master/LICENSE)