Skip to main content

Sphinx extension to produce warnings when a doc needs proofreading.

Project description

Dust

Dust is a Sphinx extension that emits warnings when a document hasn’t been proofread in a while.

It prevents your doc from accumulating dust!

Setting up

Install dust from pip:

$ pip install sphinx-dust

Then add it as an extension to your project’s conf.py:

# conf.py
extensions = [
    'dust',
]

Optionally, configure the value of dust_days_limit to your convenience (defaults to 30):

# conf.py
dust_days_limit = 30

If you only want to benefit from the generated note, configure the dust_emit_warnings attribute (defaults to True):

# conf.py
dust_emit_warnings = False

Using dust

Dust introduces a new directive: reviewer-meta.

It takes two arguments:

  • written-on, the date the document was redacted; and,

  • proofread-on, the date the document was proofread.

Both dates must respect the yyyy-mm-dd format.

Here it is in context:

.. index.rst

Rubik's Cube Tutorial
---------------------

.. reviewer-meta::
    :written-on: 1974-05-19
    :proofread-on: 1974-06-20

This directive will be replaced by a note reading:

.. note::

    Written on 19 May 1974, proofread on 20 June 1974

Running sphinx-build will output a warning if the number of days spanning between written-on and proofread-on is greater than dust_days_limit. In this case, with dust_days_limit = 30, Sphinx will emit a warning:

/path/to/your/doc/index.rst:2: WARNING: This document hasn't been proofread for 32 days

Using Sphinx’s -W option, warnings will be turned into errors, useful to make CI builds fail and be notified of outdated docs.

The warning and note content are exported using sphinx.locale so you can translate them in your language if you see fit.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinx-dust-1.1.tar.gz (3.5 kB view details)

Uploaded Source

Built Distribution

sphinx_dust-1.1-py3-none-any.whl (5.5 kB view details)

Uploaded Python 3

File details

Details for the file sphinx-dust-1.1.tar.gz.

File metadata

  • Download URL: sphinx-dust-1.1.tar.gz
  • Upload date:
  • Size: 3.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for sphinx-dust-1.1.tar.gz
Algorithm Hash digest
SHA256 2f9ba5446421bd5df63e9033451f55ef1176604059e9984b5bdbc2192bb6c42f
MD5 d483b65b60f86c9924f6ba03b47190bd
BLAKE2b-256 ad891b7f4061c585b674ab64931024d64f33e89e67e5f8aef6196517b4d1e8f7

See more details on using hashes here.

File details

Details for the file sphinx_dust-1.1-py3-none-any.whl.

File metadata

File hashes

Hashes for sphinx_dust-1.1-py3-none-any.whl
Algorithm Hash digest
SHA256 8c2f20991204ce0b2ee1a44c6b79cffeb995535ed14a6230bf7f00a92d6fd8e0
MD5 d7671651e9ae3b1591384131017d7995
BLAKE2b-256 f90d297b71bb9d7446340b732ed4475e25cb360a42600e35e16337c63e5bb8db

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page