如何使用Sphinx

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

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

每当我在网上搜索时，都会得到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::和一个角色: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.

提供为

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