# dh-doc-privacy

A debhelper addon that removes external web resources from documentation to prevent privacy leaks and ensure installed documentation does not require network access.

## Why this tool exists

Many upstream projects include "badges" in their `README.md` (or other documentation) that display build status, test coverage, version information, etc. These badges are implemented as `<img>` tags pointing to third-party services (shields.io, GitHub Actions, GitLab CI, Read the Docs, etc.).

When the documentation is converted to HTML and installed under `/usr/share/doc/`, viewing it in a browser causes the user's system to fetch those remote images. This:

- creates unnecessary network requests,
- can leak private information (e.g., that a particular package version is installed),
- triggers Lintian warnings such as `privacy-breach-generic` or `privacy-breach-twitter`,

Manually patching every upstream README is tedious and error-prone. `dh_doc_privacy` automates the process.

## Features

- Removes remote images, iframes, and known tracking scripts from documentation.
- Supports **Markdown** (`.md`), **reStructuredText** (`.rst`), and **HTML** files.
- Preserves locally-hosted images (relative paths or data URIs).
- Cleans up surrounding markup (empty lines, orphaned substitution references, etc.).
- Rewrites files **in place** during the build.
- Automatically backs up modified files; backups are restored by `dh_clean`.
- By default processes top-level `README.md`, `README.rst`, and `README.html`.
- Can be pointed at specific files or directories.

## Installation

The tool is packaged for Debian and available in the archive:

    sudo apt install dh-doc-privacy

---
## Usage in packages

`dh_doc_privacy` must be invoked manually at an appropriate point in `debian/rules`, before documentation is built or installed.

The most common placement is in an override of `dh_auto_build` (or a hook like `execute_after_dh_auto_build`), before running tools like Sphinx, Doxygen, etc.

### Examples

    # Simple case: just clean the default top-level README files
    override_dh_auto_build:
        dh_auto_build
        dh_doc_privacy

    # Clean specific files/directories before building Sphinx docs
    override_dh_auto_build:
        dh_auto_build --buildsystem=pybuild
        dh_doc_privacy README.md docs/source/
        # then run sphinx-build ...

See the man page (`man dh_doc_privacy`) for full options.

### Options

- `-X<item>` / `--exclude=item`  
  Exclude files whose path contains `item`. Can be repeated.

## How it works

`dh_doc_privacy` detects and removes:

- Markdown image links `![alt](https://...)` and reference-style links pointing to remote URLs.
- HTML `<img src="https://...">` and `<iframe src="https://...">` tags.
- reStructuredText `.. image:: https://...` directives and substitution definitions for remote images.
- Known tracking scripts (e.g., Twitter widgets, Piwik).

Local images (relative paths like `images/logo.png` or data URIs) are left untouched.

Empty blocks and orphaned lines left after removal are cleaned up to keep the documentation readable.

## Author

Edward Betts <edward@4angle.com>

## Source and bug tracking

- Repository: https://salsa.debian.org/debian/dh-doc-privacy
- Bug tracker: https://bugs.debian.org/dh-doc-privacy

## License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
