Skip to content

Commit 530cfef

Browse files
jensensclaude
jensens
and
claude
committed
Add Sphinx documentation with Diataxis structure and GH Pages deploy
Tutorials, how-to guides, reference, and explanation sections covering the full codec: Python API, JSON type markers, BTree format, Rust architecture, performance benchmarks, optimization journal (17 entries), and security measures. Built with MyST + Shibuya theme + mxmake. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent fa75ce7 commit 530cfef

31 files changed

Lines changed: 3986 additions & 0 deletions

‎.github/workflows/docs.yml‎

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

‎docs/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
/.mxmake
2+
/.venv
3+
/html

‎docs/Makefile‎

Lines changed: 310 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,310 @@
1+
##############################################################################
2+
# THIS FILE IS GENERATED BY MXMAKE
3+
#
4+
# DOMAINS:
5+
#: core.base
6+
#: core.mxenv
7+
#: docs.sphinx
8+
#
9+
# SETTINGS (ALL CHANGES MADE BELOW SETTINGS WILL BE LOST)
10+
##############################################################################
11+
12+
## core.base
13+
14+
# `deploy` target dependencies.
15+
# No default value.
16+
DEPLOY_TARGETS?=
17+
18+
# target to be executed when calling `make run`
19+
# No default value.
20+
RUN_TARGET?=
21+
22+
# Additional files and folders to remove when running clean target
23+
# No default value.
24+
CLEAN_FS?=
25+
26+
# Optional makefile to include before default targets. This can
27+
# be used to provide custom targets or hook up to existing targets.
28+
# Default: include.mk
29+
INCLUDE_MAKEFILE?=include.mk
30+
31+
# Optional additional directories to be added to PATH in format
32+
# `/path/to/dir/:/path/to/other/dir`. Gets inserted first, thus gets searched
33+
# first.
34+
# No default value.
35+
EXTRA_PATH?=
36+
37+
## core.mxenv
38+
39+
# Primary Python interpreter to use. It is used to create the
40+
# virtual environment if `VENV_ENABLED` and `VENV_CREATE` are set to `true`.
41+
# If global `uv` is used, this value is passed as `--python VALUE` to the venv creation.
42+
# uv then downloads the Python interpreter if it is not available.
43+
# for more on this feature read the [uv python documentation](https://docs.astral.sh/uv/concepts/python-versions/)
44+
# Default: python3
45+
PRIMARY_PYTHON?=3.13
46+
47+
# Minimum required Python version.
48+
# Default: 3.9
49+
PYTHON_MIN_VERSION?=3.13
50+
51+
# Install packages using the given package installer method.
52+
# Supported are `pip` and `uv`. If uv is used, its global availability is
53+
# checked. Otherwise, it is installed, either in the virtual environment or
54+
# using the `PRIMARY_PYTHON`, dependent on the `VENV_ENABLED` setting. If
55+
# `VENV_ENABLED` and uv is selected, uv is used to create the virtual
56+
# environment.
57+
# Default: pip
58+
PYTHON_PACKAGE_INSTALLER?=uv
59+
60+
# Flag whether to use a global installed 'uv' or install
61+
# it in the virtual environment.
62+
# Default: false
63+
MXENV_UV_GLOBAL?=true
64+
65+
# Flag whether to use virtual environment. If `false`, the
66+
# interpreter according to `PRIMARY_PYTHON` found in `PATH` is used.
67+
# Default: true
68+
VENV_ENABLED?=true
69+
70+
# Flag whether to create a virtual environment. If set to `false`
71+
# and `VENV_ENABLED` is `true`, `VENV_FOLDER` is expected to point to an
72+
# existing virtual environment.
73+
# Default: true
74+
VENV_CREATE?=true
75+
76+
# The folder of the virtual environment.
77+
# If `VENV_ENABLED` is `true` and `VENV_CREATE` is true it is used as the
78+
# target folder for the virtual environment. If `VENV_ENABLED` is `true` and
79+
# `VENV_CREATE` is false it is expected to point to an existing virtual
80+
# environment. If `VENV_ENABLED` is `false` it is ignored.
81+
# Default: .venv
82+
VENV_FOLDER?=.venv
83+
84+
# mxdev to install in virtual environment.
85+
# Default: mxdev
86+
MXDEV?=mxdev
87+
88+
# mxmake to install in virtual environment.
89+
# Default: mxmake
90+
MXMAKE?=mxmake
91+
92+
## docs.sphinx
93+
94+
# Documentation source folder.
95+
# Default: docs/source
96+
DOCS_SOURCE_FOLDER?=sources
97+
98+
# Documentation generation target folder.
99+
# Default: docs/html
100+
DOCS_TARGET_FOLDER?=html
101+
102+
# Documentation linkcheck output folder.
103+
# Default: docs/linkcheck
104+
DOCS_LINKCHECK_FOLDER?=docs/linkcheck
105+
106+
# Documentation Python requirements to be installed (via pip).
107+
# No default value.
108+
DOCS_REQUIREMENTS?=myst_parser sphinxcontrib.mermaid shibuya sphinx-design sphinx-copybutton
109+
110+
##############################################################################
111+
# END SETTINGS - DO NOT EDIT BELOW THIS LINE
112+
##############################################################################
113+
114+
INSTALL_TARGETS?=
115+
DIRTY_TARGETS?=
116+
CLEAN_TARGETS?=
117+
PURGE_TARGETS?=
118+
119+
export PATH:=$(if $(EXTRA_PATH),$(EXTRA_PATH):,)$(PATH)
120+
121+
# Defensive settings for make: https://tech.davis-hansson.com/p/make/
122+
SHELL:=bash
123+
.ONESHELL:
124+
# for Makefile debugging purposes add -x to the .SHELLFLAGS
125+
.SHELLFLAGS:=-eu -o pipefail -O inherit_errexit -c
126+
.SILENT:
127+
.DELETE_ON_ERROR:
128+
MAKEFLAGS+=--warn-undefined-variables
129+
MAKEFLAGS+=--no-builtin-rules
130+
131+
# mxmake folder
132+
MXMAKE_FOLDER?=.mxmake
133+
134+
# Sentinel files
135+
SENTINEL_FOLDER?=$(MXMAKE_FOLDER)/sentinels
136+
SENTINEL?=$(SENTINEL_FOLDER)/about.txt
137+
$(SENTINEL): $(firstword $(MAKEFILE_LIST))
138+
@mkdir -p $(SENTINEL_FOLDER)
139+
@echo "Sentinels for the Makefile process." > $(SENTINEL)
140+
141+
##############################################################################
142+
# mxenv
143+
##############################################################################
144+
145+
OS?=
146+
147+
# Determine the executable path
148+
ifeq ("$(VENV_ENABLED)", "true")
149+
export VIRTUAL_ENV=$(abspath $(VENV_FOLDER))
150+
ifeq ("$(OS)", "Windows_NT")
151+
VENV_EXECUTABLE_FOLDER=$(VIRTUAL_ENV)/Scripts
152+
else
153+
VENV_EXECUTABLE_FOLDER=$(VIRTUAL_ENV)/bin
154+
endif
155+
export PATH:=$(VENV_EXECUTABLE_FOLDER):$(PATH)
156+
MXENV_PYTHON=python
157+
else
158+
MXENV_PYTHON=$(PRIMARY_PYTHON)
159+
endif
160+
161+
# Determine the package installer
162+
ifeq ("$(PYTHON_PACKAGE_INSTALLER)","uv")
163+
PYTHON_PACKAGE_COMMAND=uv pip
164+
else
165+
PYTHON_PACKAGE_COMMAND=$(MXENV_PYTHON) -m pip
166+
endif
167+
168+
MXENV_TARGET:=$(SENTINEL_FOLDER)/mxenv.sentinel
169+
$(MXENV_TARGET): $(SENTINEL)
170+
ifneq ("$(PYTHON_PACKAGE_INSTALLER)$(MXENV_UV_GLOBAL)","uvfalse")
171+
@$(PRIMARY_PYTHON) -c "import sys; vi = sys.version_info; sys.exit(1 if (int(vi[0]), int(vi[1])) >= tuple(map(int, '$(PYTHON_MIN_VERSION)'.split('.'))) else 0)" \
172+
&& echo "Need Python >= $(PYTHON_MIN_VERSION)" && exit 1 || :
173+
else
174+
@echo "Use Python $(PYTHON_MIN_VERSION) over uv"
175+
endif
176+
@[[ "$(VENV_ENABLED)" == "true" && "$(VENV_FOLDER)" == "" ]] \
177+
&& echo "VENV_FOLDER must be configured if VENV_ENABLED is true" && exit 1 || :
178+
@[[ "$(VENV_ENABLED)$(PYTHON_PACKAGE_INSTALLER)" == "falseuv" ]] \
179+
&& echo "Package installer uv does not work with a global Python interpreter." && exit 1 || :
180+
ifeq ("$(VENV_ENABLED)", "true")
181+
ifeq ("$(VENV_CREATE)", "true")
182+
ifeq ("$(PYTHON_PACKAGE_INSTALLER)$(MXENV_UV_GLOBAL)","uvtrue")
183+
@echo "Setup Python Virtual Environment using package 'uv' at '$(VENV_FOLDER)'"
184+
@uv venv -p $(PRIMARY_PYTHON) --seed $(VENV_FOLDER)
185+
else
186+
@echo "Setup Python Virtual Environment using module 'venv' at '$(VENV_FOLDER)'"
187+
@$(PRIMARY_PYTHON) -m venv $(VENV_FOLDER)
188+
@$(MXENV_PYTHON) -m ensurepip -U
189+
endif
190+
endif
191+
else
192+
@echo "Using system Python interpreter"
193+
endif
194+
ifeq ("$(PYTHON_PACKAGE_INSTALLER)$(MXENV_UV_GLOBAL)","uvfalse")
195+
@echo "Install uv"
196+
@$(MXENV_PYTHON) -m pip install uv
197+
endif
198+
@$(PYTHON_PACKAGE_COMMAND) install -U pip setuptools wheel
199+
@echo "Install/Update MXStack Python packages"
200+
@$(PYTHON_PACKAGE_COMMAND) install -U $(MXDEV) $(MXMAKE)
201+
@touch $(MXENV_TARGET)
202+
203+
.PHONY: mxenv
204+
mxenv: $(MXENV_TARGET)
205+
206+
.PHONY: mxenv-dirty
207+
mxenv-dirty:
208+
@rm -f $(MXENV_TARGET)
209+
210+
.PHONY: mxenv-clean
211+
mxenv-clean: mxenv-dirty
212+
ifeq ("$(VENV_ENABLED)", "true")
213+
ifeq ("$(VENV_CREATE)", "true")
214+
@rm -rf $(VENV_FOLDER)
215+
endif
216+
else
217+
@$(PYTHON_PACKAGE_COMMAND) uninstall -y $(MXDEV)
218+
@$(PYTHON_PACKAGE_COMMAND) uninstall -y $(MXMAKE)
219+
endif
220+
221+
INSTALL_TARGETS+=mxenv
222+
DIRTY_TARGETS+=mxenv-dirty
223+
CLEAN_TARGETS+=mxenv-clean
224+
225+
##############################################################################
226+
# sphinx
227+
##############################################################################
228+
229+
# additional targets required for building docs.
230+
DOCS_TARGETS+=
231+
232+
SPHINX_BIN=sphinx-build
233+
SPHINX_AUTOBUILD_BIN=sphinx-autobuild
234+
235+
DOCS_TARGET:=$(SENTINEL_FOLDER)/sphinx.sentinel
236+
$(DOCS_TARGET): $(MXENV_TARGET)
237+
@echo "Install Sphinx"
238+
@$(PYTHON_PACKAGE_COMMAND) install -U sphinx sphinx-autobuild $(DOCS_REQUIREMENTS)
239+
@touch $(DOCS_TARGET)
240+
241+
.PHONY: docs
242+
docs: $(DOCS_TARGET) $(DOCS_TARGETS)
243+
@echo "Build sphinx docs"
244+
@$(SPHINX_BIN) $(DOCS_SOURCE_FOLDER) $(DOCS_TARGET_FOLDER)
245+
246+
.PHONY: docs-live
247+
docs-live: $(DOCS_TARGET) $(DOCS_TARGETS)
248+
@echo "Rebuild Sphinx documentation on changes, with live-reload in the browser"
249+
@$(SPHINX_AUTOBUILD_BIN) $(DOCS_SOURCE_FOLDER) $(DOCS_TARGET_FOLDER)
250+
251+
.PHONY: docs-linkcheck
252+
docs-linkcheck: $(DOCS_TARGET) $(DOCS_TARGETS)
253+
@echo "Run Sphinx linkcheck"
254+
@$(SPHINX_BIN) -b linkcheck $(DOCS_SOURCE_FOLDER) $(DOCS_LINKCHECK_FOLDER)
255+
256+
.PHONY: docs-dirty
257+
docs-dirty:
258+
@rm -f $(DOCS_TARGET)
259+
260+
.PHONY: docs-clean
261+
docs-clean: docs-dirty
262+
@test -e $(MXENV_PYTHON) && $(MXENV_PYTHON) -m pip uninstall -y \
263+
sphinx sphinx-autobuild $(DOCS_REQUIREMENTS) || :
264+
@rm -rf $(DOCS_TARGET_FOLDER)
265+
266+
INSTALL_TARGETS+=$(DOCS_TARGET)
267+
DIRTY_TARGETS+=docs-dirty
268+
CLEAN_TARGETS+=docs-clean
269+
270+
##############################################################################
271+
# Custom includes
272+
##############################################################################
273+
274+
-include $(INCLUDE_MAKEFILE)
275+
276+
##############################################################################
277+
# Default targets
278+
##############################################################################
279+
280+
INSTALL_TARGET:=$(SENTINEL_FOLDER)/install.sentinel
281+
$(INSTALL_TARGET): $(INSTALL_TARGETS)
282+
@touch $(INSTALL_TARGET)
283+
284+
.PHONY: install
285+
install: $(INSTALL_TARGET)
286+
@touch $(INSTALL_TARGET)
287+
288+
.PHONY: run
289+
run: $(RUN_TARGET)
290+
291+
.PHONY: deploy
292+
deploy: $(DEPLOY_TARGETS)
293+
294+
.PHONY: dirty
295+
dirty: $(DIRTY_TARGETS)
296+
@rm -f $(INSTALL_TARGET)
297+
298+
.PHONY: clean
299+
clean: dirty $(CLEAN_TARGETS)
300+
@rm -rf $(CLEAN_TARGETS) $(MXMAKE_FOLDER) $(CLEAN_FS)
301+
302+
.PHONY: purge
303+
purge: clean $(PURGE_TARGETS)
304+
305+
.PHONY: runtime-clean
306+
runtime-clean:
307+
@echo "Remove runtime artifacts, like byte-code and caches."
308+
@find . -name '*.py[c|o]' -delete
309+
@find . -name '*~' -exec rm -f {} +
310+
@find . -name '__pycache__' -exec rm -fr {} +

‎docs/mx.ini‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
[settings]
2+
threads = 5
3+
version-overrides =

‎docs/sources/_static/favicon.ico‎

1.09 KB
Binary file not shown.

‎docs/sources/_templates/layout.html‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{# Extend the theme's layout to inject Open Graph meta #}
2+
{% extends "!layout.html" %}
3+
4+
{% block metatags %}
5+
{{ super() }}
6+
<meta property="og:type" content="website">
7+
<meta property="og:title" content="{{ title }}">
8+
<meta property="og:description" content="Fast pickle-to-JSON transcoder for ZODB, implemented in Rust via PyO3.">
9+
<meta property="og:url" content="https://bluedynamics.github.io/zodb-json-codec/">
10+
<meta name="twitter:card" content="summary">
11+
{% endblock %}

‎docs/sources/_templates/partials/extra-head.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
<link rel="help" type="text/plain" href="/zodb-json-codec/llms.txt" title="LLM context">

0 commit comments

Comments
 (0)