Skip to content

Commit 1f55be3

Browse files
njhenrynjhenry
committed
Add Sphinx documentation served to Github pages.
1 parent be08036 commit 1f55be3

8 files changed

Lines changed: 287 additions & 1 deletion

File tree

‎.github/workflows/docs.yml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
name: Deploy docs to GitHub Pages
2+
3+
on:
4+
push:
5+
branches: [main]
6+
7+
# Allow only one concurrent deployment
8+
concurrency:
9+
group: pages
10+
cancel-in-progress: true
11+
12+
jobs:
13+
build:
14+
runs-on: ubuntu-latest
15+
steps:
16+
- uses: actions/checkout@v4
17+
18+
- uses: actions/setup-python@v5
19+
with:
20+
python-version: "3.11"
21+
22+
- name: Install package and docs dependencies
23+
run: pip install -e ".[docs]"
24+
25+
- name: Build Sphinx HTML docs
26+
run: sphinx-build -b html docs docs/_build/html -W --keep-going
27+
28+
- name: Upload Pages artifact
29+
uses: actions/upload-pages-artifact@v3
30+
with:
31+
path: docs/_build/html
32+
33+
deploy:
34+
needs: build
35+
runs-on: ubuntu-latest
36+
environment:
37+
name: github-pages
38+
url: ${{ steps.deployment.outputs.page_url }}
39+
permissions:
40+
pages: write
41+
id-token: write
42+
steps:
43+
- name: Deploy to GitHub Pages
44+
id: deployment
45+
uses: actions/deploy-pages@v4

‎CLAUDE.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,12 @@
22

33
We are recreating the R package found in `../versioning.R/` as a clean Python package with tests and documentation, so that it is fully ready to be uploaded to PyPL. The package name is "versioning".
44

5-
The purpose of this package is to parse YAML config files that simplify file reading and writing, with some opinionated package choices for file reading and writing of particular file types. The package is also intended to make it easy to deploy different versions of data pipelines over time.
5+
The purpose of this package is to parse YAML config files that simplify file reading and writing, with some opinionated package choices for file reading and writing of particular file types. The package is also intended to make it easy to deploy different versions of data pipelines over time.
6+
7+
## Documentation
8+
9+
Sphinx docs live in `docs/` and are auto-deployed to GitHub Pages on every push to `main` via `.github/workflows/docs.yml`.
10+
11+
Docstring changes and signature updates are picked up automatically. However, when you **add a new public function, class, or module**, you must manually update `docs/api.rst` with the corresponding `.. autofunction::`, `.. autoclass::`, or `.. automodule::` directive. If the new symbol depends on a new optional third-party package, also add that package to `autodoc_mock_imports` in `docs/conf.py`.
12+
13+
The version shown in the docs is read automatically from `__version__` in `src/versioning/__init__.py`; update that string when releasing a new version.

‎docs/api.rst‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
API Reference
2+
=============
3+
4+
Config
5+
------
6+
7+
.. autoclass:: versioning.Config
8+
:members:
9+
:special-members: __init__, __repr__
10+
11+
File I/O
12+
--------
13+
14+
.. autofunction:: versioning.autoread
15+
16+
.. autofunction:: versioning.autowrite
17+
18+
Format Registries
19+
-----------------
20+
21+
.. autofunction:: versioning.get_file_reading_functions
22+
23+
.. autofunction:: versioning.get_file_writing_functions
24+
25+
Utilities
26+
---------
27+
28+
.. autofunction:: versioning.pull_from_config

‎docs/conf.py‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
"""Sphinx configuration for the versioning package."""
2+
3+
import os
4+
import sys
5+
6+
# Allow building docs without installing the package (local dev)
7+
sys.path.insert(0, os.path.abspath("../src"))
8+
9+
# -- Project information -----------------------------------------------------
10+
11+
from versioning import __version__
12+
13+
project = "versioning"
14+
copyright = "2026, Nathaniel Henry"
15+
author = "Nathaniel Henry"
16+
release = __version__
17+
18+
# -- General configuration ---------------------------------------------------
19+
20+
extensions = [
21+
"sphinx.ext.autodoc",
22+
"sphinx.ext.napoleon",
23+
"sphinx.ext.viewcode",
24+
"sphinx.ext.intersphinx",
25+
]
26+
27+
intersphinx_mapping = {
28+
"python": ("https://docs.python.org/3", None),
29+
"pandas": ("https://pandas.pydata.org/docs/", None),
30+
}
31+
32+
# Mock optional heavy dependencies so docs build without them installed
33+
autodoc_mock_imports = [
34+
"pandas",
35+
"geopandas",
36+
"rasterio",
37+
"xarray",
38+
"dbfread",
39+
"openpyxl",
40+
"numpy",
41+
]
42+
43+
autodoc_default_options = {
44+
"members": True,
45+
"undoc-members": False,
46+
"show-inheritance": True,
47+
"special-members": "__init__",
48+
}
49+
50+
# NumPy-style docstrings
51+
napoleon_numpy_docstring = True
52+
napoleon_google_docstring = False
53+
napoleon_include_init_with_doc = True
54+
55+
# -- HTML output -------------------------------------------------------------
56+
57+
html_theme = "furo"
58+
59+
html_theme_options = {
60+
"source_repository": "https://github.com/henryspatialanalysis/versioning",
61+
"source_branch": "main",
62+
"source_directory": "docs/",
63+
}

‎docs/index.rst‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
versioning
2+
==========
3+
4+
YAML-based configuration management for versioned data pipelines, with
5+
automatic file I/O by extension.
6+
7+
.. code-block:: bash
8+
9+
pip install versioning
10+
11+
**Quick example:**
12+
13+
.. code-block:: python
14+
15+
from versioning import Config
16+
17+
cfg = Config("project_config.yaml")
18+
19+
# Retrieve settings
20+
cfg.get("project_name")
21+
22+
# Build paths (versioned or not)
23+
cfg.get_dir_path("results") # ~/data/results/v1
24+
cfg.get_file_path("raw", "input") # ~/data/raw/records.csv
25+
26+
# Read and write by extension
27+
df = cfg.read("raw", "input")
28+
cfg.write(df.head(10), "results", "output")
29+
30+
# Override the version at runtime
31+
cfg_v2 = Config("project_config.yaml", versions={"results": "v2"})
32+
33+
.. toctree::
34+
:maxdepth: 1
35+
:caption: Contents
36+
37+
installation
38+
api

‎docs/installation.rst‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
Installation
2+
============
3+
4+
Core package (YAML support only):
5+
6+
.. code-block:: bash
7+
8+
pip install versioning
9+
10+
With optional file-format extras:
11+
12+
.. code-block:: bash
13+
14+
pip install versioning[pandas] # CSV, TSV, Excel, Stata
15+
pip install versioning[geo] # Shapefiles, GeoJSON, GeoPackage, etc.
16+
pip install versioning[raster] # GeoTIFF and other raster formats
17+
pip install versioning[xarray] # NetCDF
18+
pip install versioning[dbfread] # DBF files
19+
pip install versioning[all] # All of the above
20+
21+
Config file structure
22+
---------------------
23+
24+
The config YAML has two special top-level keys — ``directories`` and
25+
``versions`` — alongside any arbitrary settings your pipeline needs:
26+
27+
.. code-block:: yaml
28+
29+
project_name: 'my_analysis'
30+
31+
directories:
32+
raw_data:
33+
versioned: false
34+
path: '~/data/raw'
35+
files:
36+
input_table: 'records.csv'
37+
38+
results:
39+
versioned: true
40+
path: '~/data/results'
41+
files:
42+
output_table: 'processed.csv'
43+
summary: 'summary.txt'
44+
45+
versions:
46+
results: 'v1'
47+
48+
Each entry under ``directories`` requires three fields:
49+
50+
- **versioned** (bool) — whether the directory uses version subdirectories.
51+
- **path** (str) — base path (tilde expansion is applied).
52+
- **files** (dict) — named file stubs within the directory.
53+
54+
For versioned directories the full path is ``{path}/{version}``, where the
55+
version comes from the ``versions`` dict (or a ``custom_version`` argument).
56+
57+
Supported file extensions
58+
-------------------------
59+
60+
.. list-table::
61+
:header-rows: 1
62+
:widths: 20 30 30
63+
64+
* - Format
65+
- Extensions
66+
- Requires
67+
* - CSV / TSV
68+
- csv, tsv, gz, bz2
69+
- ``pandas``
70+
* - Excel
71+
- xls, xlsx
72+
- ``pandas``, ``openpyxl``
73+
* - Stata
74+
- dta
75+
- ``pandas``
76+
* - DBF
77+
- dbf
78+
- ``dbfread``
79+
* - YAML
80+
- yaml, yml
81+
- *(core)*
82+
* - Plain text
83+
- txt
84+
- *(core)*
85+
* - Vector geospatial
86+
- shp, geojson, gpkg, fgb, gml, kml, …
87+
- ``geopandas``
88+
* - Raster
89+
- tif, geotiff
90+
- ``rasterio``
91+
* - NetCDF
92+
- nc
93+
- ``xarray``
94+
95+
For raster files, :func:`~versioning.autoread` returns
96+
``{"data": np.ndarray, "profile": dict}`` and
97+
:func:`~versioning.autowrite` accepts that same structure (or a
98+
``(data, profile)`` tuple).

‎pyproject.toml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,10 @@ all = [
3535
"xarray>=2022.3",
3636
"dbfread>=2.0",
3737
]
38+
docs = [
39+
"sphinx>=7.0",
40+
"furo>=2023.9.10",
41+
]
3842
dev = [
3943
"pandas>=1.3",
4044
"openpyxl>=3.0",

‎src/versioning/__init__.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
"""versioning: YAML-based config management for versioned data pipelines."""
22

3+
__version__ = "0.2.0"
4+
35
from versioning.config import Config
46
from versioning.autoread import autoread, get_file_reading_functions
57
from versioning.autowrite import autowrite, get_file_writing_functions

0 commit comments

Comments
 (0)