Wednesday, 23 October 2019

How to document options in an INI file with Sphinx

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 = mike@domain.com

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?

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 = mike@domain.com

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

And to refer to it in

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



from How to document options in an INI file with Sphinx

No comments:

Post a Comment