docs: Improve information on cross-referencing

Signed-off-by: Stephen Finucane <[email protected]>
Closes: #92

docs/usage.rst

@@ -59,11 +59,38 @@ Once enabled, *sphinx-click* enables automatic documentation for
    their options and their environment variables using the `Sphinx standard
    domain`_.
 
-.. _Sphinx directive: http://www.sphinx-doc.org/en/stable/extdev/markupapi.html
-.. _click-based: https://click.palletsprojects.com/en/8.0.x
-.. _Sphinx standard domain: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-standard-domain
-.. |click.core.BaseCommand| replace:: ``click.core.BaseCommand``
-.. _click.core.BaseCommand: https://click.palletsprojects.com/en/8.0.x/api/#click.BaseCommand
+
+.. _cross-referencing:
+
+Cross-referencing
+-----------------
+
+As discussed above, the documentation generated by *sphinx-click* includes
+anchors for the generated commands, their options and their environment
+variables using the `Sphinx standard domain`_. Specifically, it uses the
+|program directive|_, |option directive|_, and |envvar directive|_ directives.
+
+Options (e.g. ``--param``)
+  The ``option`` directive can be cross-referenced using the |option role|_
+  role.
+
+Environment variables
+  The ``envvar`` directive can be cross-references using the |ref role|_ role.
+  *sphinx-click* generates labels in the format
+  ``{command_name}-{param_name}-{envvar}``. It is **not** currently possible to
+  use the |envvar role|_ role because the default labels generated by Sphinx
+  are not namespaced and will generate conflicts if the same environment
+  variable is used in multiple commands. See `issue #26`__ for more
+  information.
+
+  __ https://github.com/click-contrib/sphinx-click/issues/26
+
+Programs
+  Sphinx currently does not allow you to cross-reference programs. See `Sphinx
+  issue #880`__ for more information.
+
+  __ https://github.com/sphinx-doc/sphinx/issues/880
+
 
 Example
 -------
@@ -130,7 +157,8 @@ You can also document only selected commands by using ``:commands:`` option.
       :commands: hello
 
 You can cross-reference the commands, option and environment variables using
-the roles provided by the `Sphinx standard domain`_.
+the roles provided by the `Sphinx standard domain`_. See
+:ref:`cross-referencing` for more information.
 
 .. code-block:: rst
 
@@ -206,5 +234,24 @@ assuming the group or command in ``git.git`` is named ``cli``.
 Refer to `issue #2 <https://github.com/click-contrib/sphinx-click/issues/2>`__
 for more information.
 
+.. URLs
+
+.. _Sphinx directive: http://www.sphinx-doc.org/en/stable/extdev/markupapi.html
+.. _click-based: https://click.palletsprojects.com/en/8.0.x
+.. _Sphinx standard domain: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-standard-domain
+.. |click.core.BaseCommand| replace:: ``click.core.BaseCommand``
+.. _click.core.BaseCommand: https://click.palletsprojects.com/en/8.0.x/api/#click.BaseCommand
 .. |CommandCollection| replace:: :code:`CommandCollection`
 .. _CommandCollection: https://click.palletsprojects.com/en/7.x/api/#click.CommandCollection
+.. |program directive| replace:: ``program``
+.. _program directive: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program
+.. |option directive| replace:: ``program``
+.. _option directive: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-option
+.. |envvar directive| replace:: ``program``
+.. _envvar directive: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-envvar
+.. |option role| replace:: ``:option:``
+.. _option role: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-option
+.. |ref role| replace:: ``:ref:``
+.. _ref role: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref
+.. |envvar role| replace:: ``:envvar:``
+.. _envvar role: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-envvar