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?

Khalif

There is duplicated text in the question. It looks like the second occurrence of "So having an INI file:" and the text after it can be removed. – Cataphoresis

@Cataphoresis good catch, removed the dupe part. – Hike

Polite suggestion: Would it be worth it (time/effort/etc) to convert your INI file to a config.py file? This way, you can document your config file in the same manner as the rest of your project. (This is a method we use regularly and provides a means to hyperlink project documentation directly to the associated config entry.) – Introrse

@S3DEV But documenting things with Sphinx doesn't necessarily mean they are implemented in Python. – Respective

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.

Hike

Open issues: I don't know how to reference python types from the std domain (e.g. I set :type: bool and Sphinx renders a link to docs.python.org/3/library/functions.html#bool etc). Also missing stuff like sections support, will mimic them via Sphinx section headings for now. – Hike

I think the standard library types should auto-resolve if you used intersphinx with the right mapping and programmatically substitute the proper role. Sphinx-napoleon does this transparently for its type hint fields. How it resolves types of the package being documented I don't know, or how it looks them up. But I suppose they're put into the same cross-ref type lookup index by intersphinx. – Upturn