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

Question

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

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

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

我需要更具体的内容来描述各节和选项并能够对其进行引用。

因此拥有一个INI文件：

[ui]
username = Mike
e-mail = [email protected]

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

.. 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.

提供为

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