Cross-referencing

Thanks for writing this extension!

Considering the following setup:

.. click:: test:hello
   :prog: test
   :show-nested:

It would be nice if one can refer to the resulting documentation (e.g. for one of the nested commands) just as one can reference normal functions via the directives documented in http://www.sphinx-doc.org/en/stable/domains.html#cross-referencing-python-objects .

I.e. it would be nice if something like :py:click-command:'test.hello' would insert a link to the relevant part of the documentation.

[stephenfin]

The oslo.config and oslo.policy projects from Openstack both provide custom domains with directives and roles that should be pretty easy to understand. Look for the sphinxext module in both

[stephenfin]

I suspect it should be a new, custom domain. The Sphinx docs provide examples of how to do this if you haven’t done so before. We’ll want a custom domain, at least three custom directives (command, option and envvar?) and matching roles for each. There’s no reason we couldn’t emit both the “legacy” sphinx-native stuff and new custom stuff, though I’d have no issue with a global toggle to switch this behaviour. If you can get a PoC, I’m happy to review and provide feedback. I’m also willing to be talked around on any of the above!