Generate documentation dynamically

Author: v--

.github/workflows/docs.yml

@@ -0,0 +1,34 @@
+name: Build docs
+
+on: [push]
+
+jobs:
+  docs:
+    runs-on: ubuntu-24.04
+
+    steps:
+    - uses: actions/checkout@v6
+      with:
+        # This actions is ridiculously bad at fetching tags
+        #   See https://github.com/actions/checkout/issues/2309
+        fetch-depth: 0
+        fetch-tags: true
+
+    - name: Install prerequisites on Ubuntu
+      run: |
+        sudo apt update
+        sudo apt install --yes libdjvulibre21 libdjvulibre-dev
+
+    - uses: astral-sh/setup-uv@v7
+    - name: Install dependencies
+      run: uv sync
+
+    - name: Build docs
+      run: make build-docs
+
+    - name: Upload to wiki
+      uses: spenserblack/actions-wiki@v0.3.0
+      with:
+        # Whatever directory you choose will be mirrored to the GitHub
+        # .wiki.git. The default is .github/wiki.
+        path: wiki

.gitignore

@@ -1,3 +1,4 @@
 .pytest_cache
 .ruff_cache
-.tests
+docs/dpsprep.1
+docs/dpsprep.1.txt

Makefile

@@ -1,4 +1,6 @@
-.PHONY: lint test
+SOURCE := $(wildcard dpsprep/*.py)
+
+.PHONY: lint test build-docs
 
 lint:
 	uv run ruff check
@@ -7,5 +9,18 @@ lint:
 test:
 	uv run pytest
 
-dpsprep.1: dpsprep.1.ronn
-	ronn --roff dpsprep.1.ronn
+docs:
+	mkdir docs
+
+docs/dpsprep.1: $(SOURCE) pyproject.toml docs/examples.man | docs
+	uv run click-man dpsprep \
+		--target docs \
+		--man-version $(shell git describe --tags) \
+		--man-date $(shell git log --max-count 1 --format=%as)
+
+	cat docs/examples.man >> docs/dpsprep.1
+
+docs/dpsprep.1.txt: docs/dpsprep.1
+	MANWIDTH=100 man docs/dpsprep.1 > docs/dpsprep.1.txt
+
+build-docs: docs/dpsprep.1.txt

README.md

@@ -2,7 +2,9 @@
 
 [![Tests](https://github.com/kcroker/dpsprep/actions/workflows/test.yml/badge.svg)](https://github.com/kcroker/dpsprep/actions/workflows/test.yml) [![AUR Package](https://img.shields.io/aur/version/dpsprep)](https://aur.archlinux.org/packages/dpsprep)
 
-This tool, initially made specifically for use with Sony's Digital Paper System (DPS), is now a general-purpose DjVu to PDF converter with a focus on small output size and the ability to preserve document outlines (e.g. TOC) and text layers (e.g. OCR).
+Convert DjVu files to PDF.
+
+The name comes from Sony's Digital Paper System (DPS), for which the tool was initially developed - see [below](#kevins-notes-regarding-the-first-version).
 
 ## Usage
 
@@ -18,7 +20,7 @@ You can also skip translating the text layer (it is sometimes not translated wel
 
     dpsprep --ocr '{"language": ["rus", "eng"]}' input.djvu
 
-Consult the man file ([online](./dpsprep.1.ronn)) for details; there are a lot of options to consider.
+Consult the man file ([online](./docs/dpsprep.1.txt)) for details; there are a lot of options to consider.
 
 See the next section for different ways to run the program.
 
@@ -80,7 +82,7 @@ If you want `dpsprep` to be able to use `ocrmypdf` from `pipx`'s isolated enviro
 > If you are packaging this for some other package manager, consider using PEP-517 tools as shown in [this PKGBUILD file](https://aur.archlinux.org/cgit/aur.git/tree/PKGBUILD?h=dpsprep).
 
 > [!NOTE]
-> Previous versions of the tool itself used to depend on third-party binaries, but this is no longer the case. The test fixtures are checked in, however regenerating them (see [`./fixtures/Makefile`](./fixtures/Makefile)) requires `pdflatex` (texlive, among others), `gs` (Ghostscript), `oxipng` (oxipng), `pdftotext` (Poppler), `djvudigital` (GSDjVU) and `djvused` (DjVuLibre). Similarly, the man file is checked in, but building it from markdown depends on `ronn`.
+> Previous versions of the tool itself used to depend on third-party binaries, but this is no longer the case. The test fixtures are checked in, however regenerating them (see [`./fixtures/Makefile`](./fixtures/Makefile)) requires `pdflatex` (texlive, among others), `gs` (Ghostscript), `oxipng` (oxipng), `pdftotext` (Poppler), `djvudigital` (GSDjVU) and `djvused` (DjVuLibre).
 
 ## Details
 

docs/README.md

@@ -0,0 +1,3 @@
+# dpsprep docs
+
+The documentation is built dynamically. This directory contains only auxiliary files.

docs/examples.man

@@ -0,0 +1,26 @@
+.SH EXAMPLES
+.P
+Produce `file.pdf` in the current directory:
+.IP
+dpsprep /wherever/file.djvu
+.P
+Produce `output.pdf` with reduced image quality and aggressive PDF image optimizations:
+.IP
+dpsprep --quality=30 -O3 input.djvu output.pdf
+.P
+Produce an output file using a large pool of workers:
+.IP
+dpsprep --pool=16 input.djvu
+.P
+Force bitonal images:
+.IP
+dpsprep --mode bitonal input.djvu
+.P
+Produce an output file by disregarding the text layer and running OCRmyPDF instead:
+.IP
+dpsprep --ocr '{"language": ["rus", "eng"]}' input.djvu
+.P
+Simply disregard the text layer without OCR:
+.IP
+dpsprep --no-text input.djvu
+.P

dpsprep.1

@@ -87,7 +87,7 @@ def process_text(workdir: WorkingDirectory, dpi: int | None, *, verbose: bool) -
 @click.version_option()
 @click.argument('dest', type=click.Path(exists=False, resolve_path=True), required=False)
 @click.argument('src', type=click.Path(exists=True, resolve_path=True), required=True)
-@click.command()
+@click.command(epilog='See dpsprep(1) for more details.')
 def dpsprep(  # noqa: C901
     src: str,
     dest: str | None,
@@ -104,6 +104,10 @@ def dpsprep(  # noqa: C901
     preserve_working: bool,
     no_text: bool,
 ) -> None:
+    """Convert DjVu files to PDF.
+
+    The name comes from Sony's Digital Paper System (DPS), for which the tool was initially developed.
+    """
     configure_loguru(verbose=verbose)
     workdir = WorkingDirectory(src, dest)
 

dpsprep.1.ronn

@@ -14,7 +14,7 @@ dependencies = [
   "fpdf2 (>=2.8)",
   "loguru (>=0.7)",
   "pdfrw (>=0.4)",
-  "pillow (>=12.2.0)"
+  "pillow (>=12.2.0)",
 ]
 
 [project.urls]
@@ -31,6 +31,7 @@ dpsprep = "dpsprep:dpsprep"
 
 [dependency-groups]
 dev = [
+  "click-man (>=0.5.1)",
   "mypy (>=1.19)",
   "pytest (>=9.0.3)",
   "ruff (>=0.15)",