Add hybrid mkpages and Sphinx docs build for Pages

[rsgalloway]

This pull request overhauls the documentation publishing workflow to use the mkpages static site generator and Sphinx for API docs, replacing the previous custom Jekyll-focused scripts. It also updates the documentation navigation and packaging to better support the new build system and clarify how to access the generated API reference.

The most important changes are:

Documentation Build System Migration:

• The GitHub Actions workflow .github/workflows/publish-docs.yml now builds documentation for all branches, uses mkpages for static site generation, and integrates Sphinx-generated API docs into the published site. The workflow also uploads downloadable site artifacts for all branches and only deploys to GitHub Pages from main or master. [1] [2]
• The old custom script scripts/build_pages_site.py is removed and replaced by scripts/stage_mkpages_site.py, which stages markdown docs and assets in a structure expected by mkpages and handles benchmark artifacts. [1] [2]

Docs Content and Navigation Updates:

• Adds a new docs/mkpages.yml navigation file to define sidebar and top-level navigation for the mkpages site, including direct links to the API reference.
• Updates documentation files (docs/README.md, docs/examples.md, docs/index.md) to link to the new Sphinx-generated API reference at /api/ and adjusts navigation links for the new site structure. [1] [2] [3]
• Reduces the logo size in docs/index.md for improved site appearance.

Packaging Improvements:

• Updates pyproject.toml to add a docs optional dependency group for Sphinx, and restructures the optional dependencies section for clarity and maintainability.

Minor Docstring Cleanups:

• Minor formatting improvements to docstrings in lib/pyseq/seq.py for consistency. [1] [2]

[github-actions]

Benchmark Comparison

No benchmark exceeded the +3.00% and +0.005s regression thresholds.

pyseq benchmark comparison

Baseline: detached 5d8970e Candidate: detached 2132cd4
Baseline lib: /home/runner/work/pyseq/pyseq/baseline/lib Candidate lib: /home/runner/work/pyseq/pyseq/lib
Baseline python: /opt/hostedtoolcache/Python/3.11.15/x64/bin/python Candidate python: /opt/hostedtoolcache/Python/3.11.15/x64/bin/python
Baseline pyseq: /home/runner/work/pyseq/pyseq/baseline/lib/pyseq/__init__.py Candidate pyseq: /home/runner/work/pyseq/pyseq/lib/pyseq/__init__.py
Baseline pyseq.seq: /home/runner/work/pyseq/pyseq/baseline/lib/pyseq/seq.py Candidate pyseq.seq: /home/runner/work/pyseq/pyseq/lib/pyseq/seq.py
Summary: 24 benchmarks median delta -1.49% max regression +2.31%

Benchmark	Baseline Median (s)	Candidate Median (s)	Delta (s)	Delta (%)
get_sequences_dir_contiguous_100	0.001971	0.001919	-0.000051	-2.60%
get_sequences_dir_contiguous_1000	0.019112	0.019034	-0.000077	-0.40%
get_sequences_dir_contiguous_10000	0.208868	0.203132	-0.005736	-2.75%
get_sequences_dir_mixed_100	0.002426	0.002372	-0.000054	-2.21%
get_sequences_dir_mixed_1000	0.018687	0.018333	-0.000354	-1.90%
get_sequences_dir_mixed_10000	0.193610	0.188654	-0.004956	-2.56%
get_sequences_list_contiguous_100	0.001724	0.001703	-0.000021	-1.21%
get_sequences_list_contiguous_1000	0.017261	0.017083	-0.000178	-1.03%
get_sequences_list_contiguous_10000	0.188244	0.183590	-0.004654	-2.47%
get_sequences_list_mixed_100	0.002161	0.002129	-0.000032	-1.50%
get_sequences_list_mixed_1000	0.016884	0.017273	0.000389	+2.31%
get_sequences_list_mixed_10000	0.177275	0.174641	-0.002635	-1.49%
lss_contiguous_100	0.032677	0.032564	-0.000113	-0.35%
lss_contiguous_1000	0.052706	0.051893	-0.000814	-1.54%
lss_contiguous_10000	0.241529	0.240625	-0.000904	-0.37%
lss_mixed_100	0.033483	0.033577	0.000094	+0.28%
lss_mixed_1000	0.051503	0.052080	0.000577	+1.12%
lss_mixed_10000	0.224590	0.226920	0.002329	+1.04%
resolve_sequence_contiguous_100	0.001881	0.001850	-0.000031	-1.66%
resolve_sequence_contiguous_1000	0.018355	0.018700	0.000346	+1.88%
resolve_sequence_contiguous_10000	0.201464	0.191691	-0.009772	-4.85%
resolve_sequence_mixed_100	0.001409	0.001402	-0.000007	-0.48%
resolve_sequence_mixed_1000	0.013919	0.013553	-0.000366	-2.63%
resolve_sequence_mixed_10000	0.141287	0.139024	-0.002264	-1.60%

[Copilot]

Pull request overview

Migrates the project’s documentation publishing pipeline to generate a mkpages static site and merge in Sphinx-built API reference output for GitHub Pages, replacing the previous Jekyll-oriented custom site builder.

Changes:

• Replaces the old docs staging/build script with a new mkpages staging script and updates the Pages workflow to build mkpages output + Sphinx API docs and publish objects.inv.
• Adds a minimal Sphinx project for API docs (including custom CSS) and wires the output into the published site under /api/.
• Updates docs navigation and links to point at the generated API reference, and adds a docs optional dependency group for Sphinx.

Reviewed changes

Copilot reviewed 13 out of 14 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
.github/workflows/publish-docs.yml	Builds docs for all branches, stages mkpages site, builds Sphinx API docs, merges outputs, uploads artifacts, deploys Pages from main/master only.
.gitignore	Ignores mkpages build output directory.
docs/README.md	Adds a link to the generated Sphinx API reference.
docs/examples.md	Adds a link to the generated Sphinx API reference.
docs/index.md	Adjusts home page links to include API reference and updates docs overview link.
docs/mkpages.yml	New mkpages navigation configuration including API link.
lib/pyseq/seq.py	Minor docstring formatting tweaks.
pyproject.toml	Restructures optional dependency declarations and adds docs extras for Sphinx.
scripts/build_pages_site.py	Removes the old Jekyll-focused site builder script.
scripts/stage_mkpages_site.py	New script to stage repository docs/assets into mkpages-friendly layout and embed benchmark artifacts.
sphinx/api/index.rst	New API reference page using automodule.
sphinx/conf.py	New minimal Sphinx configuration for API docs/inventory generation.
sphinx/index.rst	New Sphinx root index and toctree.
sphinx/_static/custom.css	Adds custom Sphinx styling for the API reference pages.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.