autoprogram

autoprogram copied to clipboard

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.

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

@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".

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

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

Ah, I did not understand that you meant that!

I wonder if the dot makes them invalid references.

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.