python - 如何使用 Sphinx 在 INI 文件中记录选项

Question

我想在我的 Sphinx 文档中记录一个 INI 文件。我应该使用什么标记？

每当我在网上搜索时，我都会得到 Sphinx 配置文件的描述——conf.py。

standard domain有一些工具来记录命令行程序，可以使用 describe (object) 角色，但正如文档所述“该指令产生与由提供的特定指令相同的格式域，但不创建索引条目或交叉引用目标”。

我需要更具体的内容来描述部分和选项并能够引用它们。

所以有一个 INI 文件:

[ui]
username = Mike
e-mail = mike@domain.com

我希望能够使用这样的东西:

.. ini:section:: ui

    This section contains setting for use interface 

.. ini:option:: username

    User name
    ...

有没有比编写自己的扩展程序更好的方法？

Answer 1

在研究了 Sphinx 和扩展的源代码之后，这是我想出的一个最小的解决方案。将代码片段放入您的 conf.py:

from sphinx.application import Sphinx
from sphinx.util.docfields import Field


def setup(app: Sphinx):
    app.add_object_type(
        'confval',
        'confval',
        objname='configuration value',
        indextemplate='pair: %s; configuration value',
        doc_field_types=[
            Field('type', label='Type', has_arg=False, names=('type',)),
            Field('default', label='Default', has_arg=False, names=('default',)),
        ]
    )

这添加了一对指令 .. confval:: 和一个模仿 .. option::/的角色 :confval: :option: 或 .. envvar::/:envvar: 对。

例子

Configuration
-------------

For more verbose output, increase the :confval:`verbose` parameter.
To show the traceback, set :confval:`show_traceback = True <show_traceback>`.

.. confval:: verbose

   :type: integer
   :default: 0

   More verbose output.

.. confval:: show_traceback

   :type: boolean
   :default: ``False``

   Show traceback on errors.


.. confval:: output

   :type: string
   :default: ``-``

   Target path to write the output.

呈现为

允许在整个文档中使用漂亮的交叉引用。