sphinx-contrib / sphinx-contrib/autoprogram

No apparent way to use cross-references

Open
#8 6 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
48
Forks
24
Avg merge
2h 15m
Merged PRs (30d)
1

Description

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.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing the cross-reference warnings with the documented autoprogram output and the python3 -m sphinx.ext.intersphinx targets. Compare :option: and :any: resolution for quicktile.--show-bindings with the generated std:cmdoption entries, then check both HTML and manpage output, including the SmartyPants workaround, to define the expected behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli, documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.