Metadata-Version: 2.4
Name: docpress
Version: 1.4.6
Summary: DocBook CLI: create, validate, build, and publish documents with docbook-xslTNG
Author: docpress contributors
License: MIT
Project-URL: Homepage, https://doc.press
Project-URL: Repository, https://github.com/Chaisson-Li/docpress-author
Keywords: docbook,documentation,pdf,html,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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 :: Text Processing :: Markup :: XML
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: colorama>=0.4.6
Requires-Dist: rich>=13
Requires-Dist: lxml>=5
Requires-Dist: python-ulid>=2
Requires-Dist: typing_extensions>=4
Requires-Dist: PyJWT[crypto]>=2.8
Provides-Extra: pandoc
Provides-Extra: mineru
Requires-Dist: mineru[all]>=2.0; extra == "mineru"
Provides-Extra: pdf
Requires-Dist: weasyprint<71,>=69; extra == "pdf"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: weasyprint<71,>=69; extra == "dev"
Dynamic: license-file

# DocPress

Command-line tool for creating, validating, building, and publishing [DocBook](https://tdg.docbook.org/) documents (HTML / PDF) with [docbook-xslTNG](https://xsltng.docbook.org/) and WeasyPrint.

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

## Requirements

- Python **3.10+**
- `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](docs/install/linux.md), [macOS](docs/install/macos.md), [Windows](docs/install/windows.md).
- 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](https://github.com/opendatalab/MinerU)):
  - **Cloud**: set `MINERU_TOKEN` or `DOCPRESS_MINERU_TOKEN` (no local MinerU install)
  - **Local**: `pip install "docpress[mineru]"` (pulls [`mineru[all]`](https://pypi.org/project/mineru/); 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](https://pipx.pypa.io/). Shared libraries for PDF are per system; this page does not repeat them.

```bash
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](docs/install/linux.md), [macOS](docs/install/macos.md), or [Windows](docs/install/windows.md).

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)

```bash
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`.

```bash
# 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:

```bash
# 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:

```bash
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/`](docs/funcs_review/).

## Platform notes

| Feature | Linux | macOS | Windows |
|---------|-------|-------|---------|
| create / validate / list / … | yes | yes | yes |
| build HTML | yes (compile API) | yes | yes |
| build PDF | yes (`docpress[pdf]` plus Pango; see [Linux](docs/install/linux.md)) | yes ([macOS](docs/install/macos.md)) | yes ([Windows](docs/install/windows.md)) |
| import (PDF/Office) | cloud token, or `docpress[mineru]` / local CLI | same | same |
| import (.md / .html / .json) | yes (no MinerU) | yes | yes |
| publish | `scp` / OpenSSH | OpenSSH | OpenSSH client recommended |

## Agent skill

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

## License

MIT
