Cross-referencing

[leezu]

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]

We use the built-in option, program and envvar directives provided by Sphinx. You can simply reference those using the standard Sphinx roles, like so:

:option:`dest_dir`
:program:`test`
:envvar:`my_env_var`

I'm keeping this open because we clearly need to document this better.

[kvalev]

It seems that cross referencing program directives isn't currently supported: https://github.com/sphinx-doc/sphinx/issues/880

[stephenfin]

@kvalev Indeed. Looks like this is a gap, but I think the way to resolve that is in upstream Sphinx - not here.

[kratsg]

FYI, it seems to be possible just by doing

Test, abc |cli foo|_

.. |cli foo| replace:: ``cli foo``

but I can't find documentation on this...

[abey79]

@kratsg is that a workaround of the inability to cross-reference :program:? If so, can you elaborate? I'm running into the exact same problem.

[kratsg]

If so, can you elaborate? I'm running into the exact same problem

i dropped this because i'm waiting for upstream sphinx to fix it.

[abey79]

@stephenfin Its been 4 years and it appears sphinx/issues#880 hasn't progressed at all. The inability to xref commands has been the principle short-coming of sphinx-click and forced me to resort to ugly many tricks (explicit command list and anchors so I may use :ref:cmd_XXX instead).

Are you willing to reconsider waiting for upstream to fix this, maybe by using another domain?

This could be also be combined with an automatic "code" formatting of the cross-ref, which would make sense since commands are to be typed in a terminal.

[stephenfin]

@abey79 I have no issues using our own domain. It's just a case of finding the time to do so. If you think you'd have the cycles, I'm more than happy to review something.

Reopening since this is a viable option to resolve this

[abey79]

@stephenfin I can give it a try.

Do you have any a priori idea of how this should be done? In particular:

• Did you already identify an existing domain that should be used? Or is it clear we should use our own domain?
• Should this be backward compatible, e.g. by using a new :domain: XYZ option, or would it be acceptable to outright change the domain used?

[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!

[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

[abey79]

Thanks, I'll look into that.

[s-m-e]

Just ran into this. Any progress?

I was just experimenting with potential workarounds. Imagine having a page explaining your tool, cli.html via cli.rst, one with sub commands like git:

.. _cli:

CLI
===

The command line usage of `git` ...

.. click:: git.cli:cli
  :prog: git
  :nested: full

If I want to reference e.g. git commit, the best bad thing I could do at the moment is:

:ref:`git commit <cli>`

This brings me to the top of the CLI page. However, looking at the output of sphinx-click, it has already generated an anchor: cli.html#git-commit. Why not expose this as a reference, by allowing something along the lines of:

:ref:`git commit <click-git-commit>`

Or maybe it's already exposed and I am simply overlooking something (?).

---

Full disclosure: Posted a similar message in https://github.com/sphinx-doc/sphinx/issues/880 - sorry for the partial duplicate.

[stephenfin]

Just ran into this. Any progress?

No progress on this, no. Someone needs to sit down and write the domain, directives and corresponding roles. I can review and provide guidance on this effort but don't want to write the whole thing.

I was just experimenting with potential workarounds. Imagine having a page explaining your tool, cli.html via cli.rst, one with sub commands like git:

.. _cli:

CLI
===

The command line usage of `git` ...

.. click:: git.cli:cli
  :prog: git
  :nested: full

If I want to reference e.g. git commit, the best bad thing I could do at the moment is:

:ref:`git commit <cli>`

This brings me to the top of the CLI page. However, looking at the output of sphinx-click, it has already generated an anchor: cli.html#git-commit. Why not expose this as a reference, by allowing something along the lines of:

:ref:`git commit <click-git-commit>`

Or maybe it's already exposed and I am simply overlooking something (?).

Full disclosure: Posted a similar message in sphinx-doc/sphinx#880 - sorry for the partial duplicate.

I'm afraid this is being added because of the presence of a header being generated by the extension. It's not a label that you can refer to, as you not doubt discovered if you tried referring to it via :ref:.