No apparent way to use cross-references

[ssokolow]

I've been trying to cross-reference arguments in my autoprogram output and can't find any viable way to do it.

According to python3 -m sphinx.ext.intersphinx, these are the cross-reference targets that are being generated...

std:cmdoption
        quicktile.--bindkeys                     cli.html#cmdoption-quicktile-b
        quicktile.--daemonize                    cli.html#cmdoption-quicktile-d
        quicktile.--debug                        cli.html#cmdoption-quicktile-debug
        quicktile.--help                         cli.html#cmdoption-quicktile-h
        quicktile.--no-workarea                  cli.html#cmdoption-quicktile-no-workarea
        quicktile.--show-actions                 cli.html#cmdoption-quicktile-show-actions
        quicktile.--show-bindings                cli.html#cmdoption-quicktile-show-bindings
        quicktile.--version                      cli.html#cmdoption-quicktile-v
        quicktile.-V                             cli.html#cmdoption-quicktile-v
        quicktile.-b                             cli.html#cmdoption-quicktile-b
        quicktile.-d                             cli.html#cmdoption-quicktile-d
        quicktile.-h                             cli.html#cmdoption-quicktile-h
        quicktile.command                        cli.html#cmdoption-quicktile-arg-command

...and, according to the Sphinx docs, cmdoption is a deprecated alias for option, but I get WARNING: unknown option when I try to use :option: or :any: to cross-reference either quicktile.--show-bindings or --show-bindings.

I've taken to the hacky and not-quite-right-looking solution of using this syntax for my option cross-references:

`-\\-show-bindings <cli.html#cmdoption-quicktile-show-bindings>`_

EDIT: The -\\- hack is broken in the manpage output. I had to resort to just disabling SmartyPants.
EDIT: Correction: I have to special-case manpage output because html_use_smartypants = False is getting ignored.

[merwok]

You should be able to find the targets by inspecting the objects.inv file (pickle format I think)

[ssokolow]

@merwok The python3 -m sphinx.ext.intersphinx I mentioned is a utility for dumping the contents of objects.inv in human-readable format.

My bug report is saying "Sphinx won't let me reference the targets that autoprogram puts in objects.inv".

[merwok]

My point was looking at the objects.inv contents to see that the targets to be used are!

[ssokolow]

And I said that I did, and Sphinx refused to accept what I found.

(This is far from the only time I've turned to objects.inv to figure out what type of cross-reference is necessary for a given identifier.)

[merwok]

Ah, I did not understand that you meant that!

I wonder if the dot makes them invalid references.

[ewuerger]

I followed @hroncok's mention and he found sphinx-argparse-cli. This is a newer sphinx extension that provides simple labels such that cross-referencing options or arguments is working properly via the :ref: role.