Use :envvar: to refer to variables. (was: Updated to Sphinx 1.3 to allow using :any: to reference vars)

[ypid]

Refer to the Sphinx documentation about :envvar:.
:envvar: can be used in Sphinx to reference variables. Example:

# .. envvar:: ferm__enabled
#
# Some text.
ferm__enabled: True


# .. envvar:: ferm__flush
#
# Some text.
# You might also need to change :envvar:`ferm__enabled`.
# Some text.
ferm__flush: '{{ ferm__enabled | bool }}'

When using this, we might need to adjust sections names. Example:

.. _ferm_input_list:

ferm_input_list
---------------

could be changed to:

.. _ferm_detailed_input_list:

ferm_input_list
---------------

to avoid duplicates. The good thing is that Sphinx as of 1.3.4 warns when referencing a label for which multiple targets exist.

1.3.4 has been chosen because it is the current version in jessie-backports.

Edited: Changed :any: to :envvar:. See comment

[ypid]

Actually. I think we should add a proper namespace for sections.

• ferm (role)
• section (heading)
• detailed (in the defaults-detailed.rst file as discussed in Rename Default variables: configuration to Default variable details. #139)
• input_list (variable suffix, the real thing)

.. _ferm__section_detailed_input_list:

ferm_input_list
---------------

[drybjed]

So far there is only one "target" for each default variable with detailed documentation, so for example with:

Go to :ref:`ferm__rules`

.. _ferm__rules:

ferm__rules
-----------

Everything should be covered. Do you think that there could be more targets?

[ypid]

Do you think that there could be more targets?

Actually, I do. The reason of this PR was to enable the use of the any role with which you can refer to the envvar definition in the defaults file with

:any:`ferm__rules`

Check the http://docs.debops.org/en/latest/ansible/roles/ansible-apt_install/docs/changelog.html#v0-1-1 in which I made use of this feature.

[drybjed]

OK, I presume that works. However, some of the variable names are long already an writing a nice paragraph that looks OK in the file is sometimes hard, I wouldn't want to add section_detailed to each one, maybe something shorter? Let's see...

Go to :ref:`ferm__ref_dependent_rules`

.. ferm__ref_dependent_rules:

ferm__dependent_rules
---------------------

What do you think?

[ypid]

@drybjed Nice 👍 Lets go with that.

[drybjed]

OK.

[ypid]

@ganto has read the Sphinx documentation more carefully then I did and uses :envvar: in https://github.com/debops/ansible-slapd/pull/26.

I think :envvar: is the better way to refer to variables. I updated my comment at the top.