sphinx-dust 1.2.4

Dust

Dust是一个Sphinx扩展，当文档有一段时间未校对时，会发出警告。

它可以防止您的文档积累灰尘！

设置

使用pip安装dust

$ pip install sphinx-dust

然后将它添加到项目的conf.py中作为扩展

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

使用dust

Dust引入了一个新的指令：reviewer-meta。

它需要两个参数

• written-on，文档被编辑的日期；以及，

• proofread-on，文档被校对的日期。

• dust-days-limit，覆盖全局dust_days_limit，以自定义文档可以不经过审查而存在的天数。

这两个日期必须遵守yyyy-mm-dd格式。

以下是上下文信息

.. index.rst

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

.. reviewer-meta::
    :written-on: 1974-05-19
    :proofread-on: 1974-06-20
    :dust-days-limit: 25

此指令将被替换为以下注释

.. note::

    Written on 19 May 1974, proofread on 20 June 1974

运行sphinx-build时，如果written-on和proofread-on之间的天数超过dust_days_limit，则会输出警告。在这种情况下，如果dust_days_limit = 30，Sphinx将发出警告

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

使用Sphinx的-W选项，警告将被转换为错误，这有助于使CI构建失败并通知过时的文档。

警告和注释内容通过sphinx.locale导出，因此您可以将其翻译成您喜欢的语言。

配置

可以调整各种参数以方便使用。您可以在项目的conf.py文件中更改其中任何一个，它们是简单的Python变量。

您可以分配任何值给这些设置，但是您应该尊重它们的类型，否则扩展可能会崩溃。

以下是一份完整的参数列表

• dust_days_limit（默认：30），自上次审查以来文档可以存活的天数，不会发出警告，

• dust_emit_warnings（默认：True），控制扩展在文档需要审查时是否发出警告，

• dust_include_output（默认：True），控制是否在监控文档中包含HTML输出，

• dust_output_format（默认："Written on {written_on}, proofread on {proofread_on}"），HTML输出的内容，需要包含两个格式变量：written_on和proofread_on，它们将由strftime格式化后的written-on和proofread-on值替换，

• dust_datetime_format（默认："%d %B %Y"），在HTML输出中格式化日期时间（written-on和proofread-on值）；以及，

• dust_node_classes（默认：['note']），用于生成HTML的节点的Sphinx告诫类列表。