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

Question

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

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

该标准领域有一些工具，以文件的命令行程序和一个可以使用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::和一个: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.

呈现为

允许在整个文档中进行良好的交叉引用。