Cross Referencing Program Objects

[shimizukawa]

I'm using Sphinx to document a software product that includes a number
of command line utilities. I've documented the utilities themselves
using the standard domain's "program" and "option" directive, but I
find myself often talking about these programs in the text of the
documentation itself, and I would like to be able to cross reference
the "manual page," when I mention the program's name.

The easiest/best way would be if the :program: role would link to the
page that has "program" directive.

In an attempt to find a work around for this I've encountered another
issue:

I attempted create a new "binary" role and directive combination in a
custom domain, inserted these "binary" directives with the name of the
utility on the same manual page that has a program directive and
discovered that cross-referencing would not work for these links, even
though the "binary" and the "program" directives exist in different
domains. At the same time cross-references work if when "binary"
directive holds a term that isn't duplicated by the value of a program
directive.

Is there a work around for this collision, or a recommended way of
referencing these kinds of objects.

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/880
• Originally reported by: tychoish
• Originally created at: 2012-02-16T22:37:19.691

[kvalev]

It seems that cross-referencing an program directive is not possible, right?

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

[ulijh]

I can't get this to work. At least not with commands containing dashes.

[tk0miya]

The current implementation of program directive behaves like a context switcher. It's similar to currentmodule directive. To realize the cross-reference feature, we need to generate an anchor to the definition. But I worried it causes conflicts. It might be better to add a new directive for such purpose. But I don't have a good naming ideas...

[waveform80]

The current implementation of program directive behaves like a context switcher. It's similar to currentmodule directive. To realize the cross-reference feature, we need to generate an anchor to the definition. But I worried it causes conflicts. It might be better to add a new directive for such purpose. But I don't have a good naming ideas...

Given the option directive already generates anchors (taking part of their identifier from the preceding program directive), could the program directive not similarly generate an anchor. In other words, make it akin to the module directive, as opposed to the currentmodule directive?

I'm probably missing something, but looking at the markup generated in our pinout -h documentation and the anchor being "cmdoption-pinout-h" which is obviously composed of the .. program:: pinout and .. option:: -h directives declaring it, I would assume that an anchor like "cmdoption-pinout" (with no option portion) or "cmd-pinout" (if a different prefix were preferable) would be reasonably unique?

[jakobandersen]

You may have multiple places in a document where you use .. program:: so it is not clear which should generate the anchor. Similarly the py:currentmodule directive can be used multiple time.
But perhaps we could figure out a good name for a new directive which defines the anchor and shows the options for the program, or similar.

[waveform80]

You may have multiple places in a document where you use .. program:: so it is not clear which should generate the anchor. Similarly the py:currentmodule directive can be used multiple time. But perhaps we could figure out a good name for a new directive which defines the anchor and shows the options for the program, or similar.

Re-reading the docs for the program directive you're clearly correct, and I've obviously been under the mistaken impression that the program directive was like the module directive (i.e. that it's used in a single place in the docs to define "this is the start of the documentation for program/module X").

That said, I'm struggling to imagine where/why one might wish to split up the options for a program in a set of documentation (again, I may be missing something obvious). Realizing that I'm proposing something that would potentially break backwards compatibility, might it be preferable to re-define the program directive along the lines of the module directive, and introduce a currentprogram directive (akin to the currentmodule directive)?

Alternatively, rather than breaking compatibility (and in keeping with the OP), perhaps introduce a binary directive and a corresponding currentbinary directive (the latter effectively being an alias of the existing program directive, which could potentially be deprecated in favour of currentbinary at some future point)?

Come to think of it, I'm not entirely sold on "binary" -- it's a bit too all-encompassing. Perhaps "executable" or "application" (or possibly "script", though that comes with its own implications) to make it clear that the binary in question is something intended to be run by the user?

[s-m-e]

Just ran into this. Idea for a potential workaround that would not break backwards compatibility (?):

Imaging 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, 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>`

Maybe this is a less invasive change?