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 = [
    'sphinx_dust',
]

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.

  • dust-days-limit, overrides the global dust_days_limit to customize the day the document can live without review.

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
    :dust-days-limit: 25

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.

Configuration

Various parameters can be tweaked to your convenience. You can alter any of them in your project’s conf.py file, they’re simple Python variables.

You can assign any value to these settings, however you should respect their typing, the extension could crash otherwise.

Here’s an exhaustive list of every parameter:

  • dust_days_limit (default: 30), the number of days a document can live since its last reviewing without emitting warnings,

  • dust_emit_warnings (default: True), controls whether the extension emits a warning when a document needs reviewing,

  • dust_include_output (default: True), controls whether to include an HTML output in the monitored documents,

  • dust_output_format (default: "Written on {written_on}, proofread on {proofread_on}"), the content of the HTML output, needs to include two format variables: written_on and proofread_on, which will get replaced by the result of strftime-formatting written-on and proofread-on values,

  • dust_datetime_format (default: "%d %B %Y"), the format datetimes (written-on and proofread-on values) take in HTML output; and,

  • dust_node_classes (default: ['note']), a list of Sphinx admonition classes to apply to the node used to generate HTML.

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.2.4.tar.gz (4.2 kB view details)

Uploaded Source

Built Distribution

sphinx_dust-1.2.4-py3-none-any.whl (4.3 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: sphinx-dust-1.2.4.tar.gz
  • Upload date:
  • Size: 4.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.11.0 pkginfo/1.4.2 requests/2.19.1 setuptools/40.2.0 requests-toolbelt/0.8.0 tqdm/4.25.0 CPython/3.4.4

File hashes

Hashes for sphinx-dust-1.2.4.tar.gz
Algorithm Hash digest
SHA256 0d7b4dfad9860f525c4313fc4ec8edcb13634f901fbece77f966e5adf5005739
MD5 a537a6a37200c5b0fdb898cb281f5b09
BLAKE2b-256 ff9d795079692519ade2a0013328aa74616b630fa4895ddc0362b1d6c411ed3d

See more details on using hashes here.

File details

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

File metadata

  • Download URL: sphinx_dust-1.2.4-py3-none-any.whl
  • Upload date:
  • Size: 4.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.11.0 pkginfo/1.4.2 requests/2.19.1 setuptools/40.2.0 requests-toolbelt/0.8.0 tqdm/4.25.0 CPython/3.4.4

File hashes

Hashes for sphinx_dust-1.2.4-py3-none-any.whl
Algorithm Hash digest
SHA256 ea61feddc0eadbd1fd252d7b9b05f85fba4ea3f567f26a8cabe619917239d42e
MD5 110319768466ce56d2044ace2cea761e
BLAKE2b-256 79319a28c08f131312864e02bfc48c95b0adfa61893f7e5cf59e54d29c4e0776

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