How to document options in an INI file with Sphinx

Question

I'd like to document an INI file in my Sphinx documentation. What markup should I use?

Whenever I search the Web I get description of Sphinx configuration file—conf.py.

The standard domain has some tools to document command-line programs and one could use describe (object) role but as the documentation states "This directive produces the same formatting as the specific ones provided by domains, but does not create index entries or cross-referencing targets".

I need something more specific to describe sections and options and to be able to refer to them.

So having an INI file:

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

I would like to be able to use something like this:

.. ini:section:: ui

    This section contains setting for use interface 

.. ini:option:: username

    User name
    ...

Is there better way to do that than writing my own extension?

Answer 1

After studying Sphinx and extensions' source code, this is a minimal solution I came up with. Put the snippet into your 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',)),
        ]
    )

This adds a pair of directive .. confval:: and a role :confval: that mimic the .. option::/:option: or .. envvar::/:envvar: pairs.

Example

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.

renders as

allowing for nice crossrefs throughout the docs.