DocPress

Command-line tool for creating, validating, building, and publishing DocBook documents (HTML / PDF) with docbook-xslTNG and WeasyPrint.

Official site (static HTML, zh / en): website/. Open website/index.html locally, or python3 -m http.server 8080 --directory website.

Requirements

• Python 3.10+
• Java / JRE is not required. docpress build posts the pack to the compile service and prints PDF locally with WeasyPrint. Sign in with docpress login (account URL: DOCPRESS_ACCOUNT_URL, else ~/.config/docpress/account-url). The token is stored in ~/.config/docpress/credentials (mode 0600) and is never written to docspace.xml. A lab machine can set DOCPRESS_COMPILE_DEV_SECRET instead of logging in; document commands then also need DOCPRESS_DEV_NO_LICENSE=1. Compile address: DOCPRESS_COMPILE_API_URL, else ~/.config/docpress/compile-api-url (Windows: %APPDATA%\docpress\compile-api-url), else http://127.0.0.1:8765. Without a reachable compile API, build fails.
• PDF (pipx install "docpress[pdf]") plus the Pango libraries for your system. Commands: Linux, macOS, Windows.
• Formulas and Mermaid are rendered on the compile host, not on the author machine. The compile service lives in the docpress-compile repository.
• Optional for docpress import of PDF/Office (MinerU):
  • Cloud: set MINERU_TOKEN or DOCPRESS_MINERU_TOKEN (no local MinerU install)
  • Local: pip install "docpress[mineru]" (pulls mineru[all]; large). Or install MinerU yourself and ensure mineru is on PATH / set MINERU_BIN
  • Not required for .md / .html / MinerU-style content_list .json

Install

Python 3.10+ and pipx. Shared libraries for PDF are per system; this page does not repeat them.

pipx install docpress
pipx install "docpress[pdf]"

docpress is enough to create, validate, and build HTML. PDF needs the second command, after the libraries on Linux, macOS, or Windows.

A bare install does not pull WeasyPrint. HTML via a compile API still works; build -f pdf.* then prints pip install 'docpress[pdf]' (that is the message from the program).

Optional local PDF/Office import stays a separate extra: pip install "docpress[mineru]".

Install (development)

cd /path/to/docpress-author
python3 -m venv .venv
# Linux/macOS:
source .venv/bin/activate
# Windows:
# .venv\Scripts\activate

pip install -U pip
pip install -e ".[dev]"
# Optional local PDF/Office import:
# pip install -e ".[mineru]"

The compile service is the separate docpress-compile repository. This repository packs the zip and prints PDF. The pack records xslTNG 2.8.2, the version in the compile image.

Quick start

docspace.xml lives in the docpress install home (dp_home), not in the directory you happen to run the command from. For a source/editable tree that is the folder that contains pyproject.toml (a checkout of docpress-author). You can cd anywhere; docpress still reads {dp_home}/docspace.xml.

Override only when the install root cannot be inferred (pure wheel / site-packages): export DOCPRESS_HOME=/path/to/install-home.

# First command creates {dp_home}/docspace.xml if missing
# (defaults: name=folder name, library={dp_home}/library). Press Enter to accept.
# Account URL is separate from the compile API. No default port.
export DOCPRESS_ACCOUNT_URL=http://127.0.0.1:8080
docpress login --email you@example.com
docpress create mybook -d book
docpress validate mybook
# Default build sends the login token as Bearer.
# Persist the compile address in ~/.config/docpress/compile-api-url if you prefer;
# DOCPRESS_COMPILE_API_URL still overrides that file. Never put a secret or token in the file.
# Lab only (no login): export DOCPRESS_COMPILE_DEV_SECRET=… and DOCPRESS_DEV_NO_LICENSE=1
docpress build mybook -f html.s
docpress build mybook -f pdf.s

In scripts/CI (non-interactive), the first command that needs a document space silently creates docspace.xml at dp_home with the same defaults ({dp_home}/library). Edit the file afterward if you need a custom library path, name, git URL, or publish target.

Document types: book, article, brief.

Override bundled assets (advanced): export DOCPRESS_ASSETS=/path/to/assets.

Import and MinerU

docpress import for Markdown / HTML / content_list JSON needs no MinerU.

Markdown import normalizes Pandoc output automatically (leading > metadata blocks, blockquote/hard-break literallayout → note/para); you do not need special MD syntax.

For PDF / Office, choose one:

# A) Local MinerU (optional extra — large: torch / models)
pip install "docpress[mineru]"

# B) Cloud API (no local MinerU package)
export MINERU_TOKEN=your_token
# or: export DOCPRESS_MINERU_TOKEN=your_token
# or: ~/.mineru/config.yaml with a "token:" line

Example:

docpress import ./paper.pdf MyPaper -d article

If the local CLI is missing, the error message also suggests pip install "docpress[mineru]". Optional per-run override (PDF/Office only): docpress import ./paper.pdf MyPaper --engine local. Advanced: MINERU_BIN / DOCPRESS_MINERU, DOCPRESS_MINERU_ENGINE=cloud|local|auto.

Import routes, token setup, and --engine are documented in docs/funcs_review/.

Platform notes

Agent skill

An agent-agnostic skill for filing engineering notes as DocBook into a user docspace library (create / validate / build via the CLI) lives at share/agent-skills/docpress/. See share/agent-skills/docpress/install.md for Cursor / Workbuddy install (copy or symlink; not installed by pip).

License

MIT