如何使用 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 和扩展的源代码后，这是我想出的最小解决方案。将 sn-p 放入您的 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:: 和一个角色 :confval:，它们模仿 .. option::/: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.

呈现为

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