Metadata-Version: 2.4
Name: sphinxpress
Version: 0.1.0
Summary: Publish multiple Sphinx documentation projects as one Jekyll site, PDF, or EPUB.
Author: Holger Nahrstaedt
License-Expression: MIT
Project-URL: Homepage, https://github.com/buchwandler/sphinxpress
Project-URL: Repository, https://github.com/buchwandler/sphinxpress
Project-URL: Issues, https://github.com/buchwandler/sphinxpress/issues
Project-URL: Documentation, https://buchwandler.de/tools/sphinxpress/
Keywords: sphinx,jekyll,documentation,github-pages,epub,pdf
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: sphinx>=7
Requires-Dist: typer>=0.12
Requires-Dist: PyYAML>=6
Requires-Dist: jinja2>=3.1
Requires-Dist: tomli-w>=1.0
Requires-Dist: tomli>=2; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: types-PyYAML; extra == "dev"
Provides-Extra: docs
Requires-Dist: myst-parser>=2; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2; extra == "docs"
Dynamic: license-file

# sphinxpress

`sphinxpress` publishes multiple independent Sphinx documentation projects as one documentation product: generated Jekyll/GitHub Pages pages, a combined EPUB, and a combined PDF.

It stays Sphinx-first. Each source project keeps its own `conf.py` and documentation tree. `sphinxpress` runs Sphinx builders, reads their output, and writes deterministic site and book artifacts for a larger publishing pipeline.

> Release status: early alpha. Pin versions and validate generated output before using in production documentation pipelines.

## Features

- Build Jekyll pages from Sphinx JSON output.
- Write per-project navigation data for site layouts.
- Build aggregate EPUB and PDF projects from selected Sphinx docs projects.
- Resolve release metadata from manual tags, git tags, or project metadata.
- Optionally create a shared managed virtual environment for Sphinx and documentation dependencies.

## Install

```bash
python -m pip install sphinxpress
```

For local development and documentation builds:

```bash
python -m pip install -e ".[dev,docs]"
python -m pytest -q
```

## Minimal configuration

Create `sphinxpress.toml` at the repository root:

```toml
[site]
root = "site"
base_url = "https://docs.example.com"
tools_dir = "tools"
nav_data_dir = "_data/tool_nav"
layout = "tool-doc"
title = "Example Docs"

[build]
work_dir = ".sphinxpress"
sphinx_build = "sphinx-build"
fail_on_warning = true
keep_build_dir = false
parallel = "auto"

[book]
title = "Example Documentation"
author = "Example Team"
language = "en"
project_order = ["tool-a"]

[pdf]
builder = "latexpdf"
output = "dist/example-documentation.pdf"

[epub]
builder = "epub"
output = "dist/example-documentation.epub"

[release]
tag_prefix = "v"
release_url_template = "{repo_url}/releases/tag/{tag}"

[[projects]]
name = "tool-a"
title = "Tool A"
docs_root = "../tool-a/docs"
conf_dir = "../tool-a/docs"
root_doc = "index"
repo_url = "https://github.com/example/tool-a"
release_strategy = "manual"
release_tag = "v0.1.0"
```

## Commands

```bash
sphinxpress check
sphinxpress list
sphinxpress build-site --all
sphinxpress build-epub --all
sphinxpress build-pdf --all
sphinxpress validate
```

`build-pdf` uses Sphinx's `latexpdf` builder and requires LaTeX system dependencies.

## Managed build environment

`sphinxpress` can create one shared virtual environment for Sphinx and documentation dependencies:

```toml
[build.env]
enabled = true
scope = "shared"
python = "python3"
path = ".sphinxpress/venv"
upgrade_pip = true
packages = [
  "sphinx>=7",
  "myst-parser",
  "sphinx-rtd-theme",
  "-e", "../tool-a",
]
```

For v0.1, only `scope = "shared"` is supported. `scope = "project"` is reserved for a future release and is rejected with a configuration error.

Package path arguments after `-e`, `--editable`, `-r`, `--requirement`, `-c`, and `--constraint` are resolved relative to `sphinxpress.toml`.

## Documentation

Build the project documentation with:

```bash
python -m pip install -e ".[dev,docs]"
python -m sphinx -b html docs docs/_build/html
```
