Merge pull request #50 from kcroker/maintenance

Maintenance

Author: v--

.github/workflows/docs.yml

@@ -0,0 +1,36 @@
+name: Build docs
+
+on:
+  push:
+    branches:
+      - master
+
+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
+        mkdir .github/wiki
+        cp docs/Home.md docs/dpsprep.1.md .github/wiki
+
+    - name: Upload to wiki
+      uses: spenserblack/actions-wiki@v0.3.0

.github/workflows/test.yml

@@ -12,7 +12,9 @@ jobs:
     runs-on: ${{ matrix.os }}
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v6
+      with:
+          submodules: true
 
     - name: Install prerequisites on Ubuntu
       if: matrix.os == 'ubuntu-24.04'
@@ -22,7 +24,7 @@ jobs:
 
     - name: Install prerequisites on macOS
       if: matrix.os == 'macos-14'
-      run: brew install djvulibre libtiff
+      run: brew install djvulibre
 
     # - name: Install prerequisites on Windows
     #   if: matrix.os == 'windows-2022'

.gitignore

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

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "ruff-config"]
+  path = ruff-config
+  url = git@github.com:v--/ruff-config.git

CHANGELOG.md

@@ -1,153 +1,164 @@
-## v2.5.4 (2026-04-24)
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+* Maintenance
+
+## 2.5.4 - 2026-04-24
 
 * Run `uv` security audit and update some dependencies
 
-## v2.5.3 (2026-03-25)
+## 2.5.3 - 2026-03-25
 
 * Fix broken workflow without text layer translation
 * Shorter names for temporary directories
 * Code maintenance
 
-## v2.5.2 (2026-03-25)
+## 2.5.2 - 2026-03-25
 
 * Relax dependency versions
 
-## v2.5.1 (2026-03-14)
+## 2.5.1 - 2026-03-14
 
 * Allow manually configuring PDF page resolution (DPI)
 
-## v2.5.0 (2026-03-13)
+## 2.5.0 - 2026-03-13
 
 * Account for DjVu file resolution
 * Simplify image diffing and regenerate better-quality fixtures
 
-## v2.4.2 (2026-02-24)
+## 2.4.2 - 2026-02-24
 
 * Fix issue where only the main process has its logger configured
 
-## v2.4.1 (2026-02-24)
+## 2.4.1 - 2026-02-24
 
 * Fix compatibility issues with the new OCRmyPDF API
 * Remove support for Python 3.10
 
-## v2.4.0 (2026-02-24)
+## 2.4.0 - 2026-02-24
 
 * Migrate to `uv` from `pyenv` + `poetry`
 * Update dependencies
 
-## v2.3.1 (2025-10-28)
+## 2.3.1 - 2025-10-28
 
 * Fix mixed-up email format
 
-## v2.3.0 (2025-10-28)
+## 2.3.0 - 2025-10-28
 
 * Remove support for Python 3.9
 * Migrate to standardized `pyproject.toml`
 * Update dependencies
 
-## v2.2.15 (2025-07-02)
+## 2.2.15 - 2025-07-02
 
 * Add support for installation via `pipx`
 
-## v2.2.14 (2025-05-27)
+## 2.2.14 - 2025-05-27
 
 * Improve installation notes
 * Bump djvulibre-python version
 
-## v2.2.13 (2025-02-12)
+## 2.2.13 - 2025-02-12
 
 * Fail-safe quality settings for non-JPEG images
 
-## v2.2.12 (2025-01-27)
+## 2.2.12 - 2025-01-27
 
 * Update pytest_image_diff and fix newly broken tests
 
-## v2.2.11 (2025-01-26)
+## 2.2.11 - 2025-01-26
 
 * Update dependencies
 
-## v2.2.10 (2024-10-25)
+## 2.2.10 - 2024-10-25
 
 * Improve interface with OCRmyPDF
 * Fix CI build
 
-## v2.2.9 (2024-10-25)
+## 2.2.9 - 2024-10-25
 
 * Improve type hints
 * Update dependencies
 
-## v2.2.8 (2024-10-18)
+## 2.2.8 - 2024-10-18
 
 * Support single characters in the text layer
 
-## v2.2.7 (2024-08-27)
+## 2.2.7 - 2024-08-27
 
 * Improve tab and newline handling
 
-## v2.2.6 (2024-08-05)
+## 2.2.6 - 2024-08-05
 
 * Fix accidental whitespace removal from text blocks
 
-## v2.2.5 (2024-07-20)
+## 2.2.5 - 2024-07-20
 
 * Re-add ability to force the image mode (RGB/Grayscale/Monochrome)
 
-## v2.2.4 (2024-02-24)
+## 2.2.4 - 2024-02-24
 
 * Update dependencies
 
-## v2.2.3 (2023-12-09)
+## 2.2.3 - 2023-12-09
 
 * Fix CI build
 * Ignore invalid UTF-8 sequences
 * Ignore unrecognized page titles in the outline (#23)
 
-## v2.2.2 (2023-10-29)
+## 2.2.2 - 2023-10-29
 
 * Update dependencies
 
-## v2.2.1 (2023-11-06)
+## 2.2.1 - 2023-11-06
 
 * Handle invalid PDF pages
 * Fix exception in text layer processing (#20)
 
-## v2.2.0 (2023-10-28)
+## 2.2.0 - 2023-10-28
 
 * Add options for disabling the text layer and for directly running OCR
 
-## v2.1.5 (2023-10-27)
+## 2.1.5 - 2023-10-27
 
 * Fix inverted colors in images (#16)
 
-## v2.1.4 (2023-10-06)
+## 2.1.4 - 2023-10-06
 
 * Fix typo in logging code
 
-## v2.1.3 (2023-10-06)
+## 2.1.3 - 2023-10-06
 
 * Improve logging
 
-## v2.1.2 (2023-10-02)
+## 2.1.2 - 2023-10-02
 
 * Accidental version bump
 
-## v2.1.1 (2023-10-02)
+## 2.1.1 - 2023-10-02
 
 * Remove debug code
 
-## v2.1.0 (2023-10-02)
+## 2.1.0 - 2023-10-02
 
 * Add support for OCRmyPDF
 
-## v2.0.2 (2023-08-03)
+## 2.0.2 - 2023-08-03
 
 * Update some other dependencies
 * Replace `python-djvulibre` with `djvulibre-python`
 
-## v2.0.1 (2023-06-22)
+## 2.0.1 - 2023-06-22
 
 * Minor improvements in packaging
 
-## v2.0.0 (2023-05-04)
+## 2.0.0 - 2023-05-04
 
 * Fully rewrite

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,20 @@ 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
+
+# Render the man page as text and indent the entire file so that it is a valid markdown code block
+docs/dpsprep.1.md: docs/dpsprep.1
+	echo -n '    ' > docs/dpsprep.1.md
+	MANWIDTH=100 man docs/dpsprep.1 | sed --null-data 's/\n/\n    /g' | head --lines=-1 >> docs/dpsprep.1.md
+
+build-docs: docs/dpsprep.1.md

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](https://github.com/kcroker/dpsprep/wiki/dpsprep.1)) for details; there are a lot of options.
 
 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/Home.md

@@ -0,0 +1,3 @@
+The only document on this wiki is the [man page](./dpsprep.1).
+
+See the README in the [repository](https://github.com/kcroker/dpsprep) for installation instructions and technical notes.

docs/README.md

@@ -0,0 +1,5 @@
+# dpsprep docs
+
+The usage documentation amounts to a simple man page, which is built dynamically and hosted at [the wiki](https://github.com/kcroker/dpsprep/wiki).
+
+See the README in the [project root](https://github.com/kcroker/dpsprep) for installation instructions and technical notes.

docs/examples.man

@@ -0,0 +1,25 @@
+.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