WARNING: unknown option for :option:

[buzz]

Description

• I receive several WARNING: unknown option: -v when building docs.
• Not all :option:`-v` are working.

To Reproduce

$ git clone https://github.com/buzz/sphinx-option-testcase.git
$ cd sphinx-option-testcase
$ python -m venv venv
$ . venv/bin/activate
$ pip install -r requirements.txt
$ make html
Running Sphinx v2.0.0
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 4 source files that are out of date
updating environment: 4 added, 0 changed, 0 removed
reading sources... [100%] otherb                                                                                                                                              
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] otherb                                                                                                                                               
/tmp/sphinx-option-testcase/cli.rst:4: WARNING: unknown option: -v
/tmp/sphinx-option-testcase/othera.rst:4: WARNING: unknown option: -v
/tmp/sphinx-option-testcase/otherb.rst:4: WARNING: unknown option: -v
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 3 warnings.

The HTML pages are in _build/html.
$ # open _build/html/index.html in browser
$ # only the 2nd reference to option -v on cli.rst worked

Expected behavior

• All four references to option -v should work regardless if they occur before or after the .. option:: -v or in another document.
• No warning should be given.

Your project Minimal test case: https://github.com/buzz/sphinx-option-testcase

Environment info

• OS: Linux 4.20.8-arch1-1-ARCH #1 SMP PREEMPT Wed Feb 13 00:06:58 UTC 2019 x86_64 GNU/Linux
• Python version: 3.7.2
• Sphinx version: 2.0.0 (same for 1.8.5)
• Sphinx extensions: none

[tk0miya]

The following example describes -v option for cli command. So it means cli -v.

.. program:: cli

.. option:: -v

    verbose

So you need to refer the -v option by :option:`cli -v` or like following:

.. program:: cli

:option:`-v`

refs: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program

[buzz]

Thanks for pointing into the right direction. Confirming it works. :+1:

I was actually reading the docs, in particular this section:

The directive will create cross-reference targets for the given options, referenceable by option (in the example case, you’d use something like :option:`dest_dir`, :option:`-m`, or :option:`--module`).

(https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-option)

It still not clear to me when to use :option:`cli -v` and just :option:`-v`.

Can the option directive be use without ..program::? Would that actually make sense?

I wished the docs would be more explicit here.

[tk0miya]

program directive works like a namespace. So if your document describes two or more commands, it works well.

.. program:: cmd_a

.. option:: -v

   -v option for cmd_a

.. program:: cmd_b

.. option:: -v

    -v option for cmd_b

In this case, Sphinx can't determine which option entry is appropriate for :option:`-v` reference without any program directive. You need to give program name to the reference explicitly (via program directive or reference name like :option:`cmd_a -v`).

Can the option directive be use without ..program::? Would that actually make sense?

If your document describes only one commend, program directive is not needed.

I wished the docs would be more explicit here.

Agreed. But I don't have good description for it at present. Do you have any idea?

[buzz]

The example I posted only uses one program, not two or more. So the description doesn't apply here.

Can the option directive be use without ..program::? Would that actually make sense?

If your document describes only one commend, program directive is not needed.

That's doesn't seem to be the whole truth.

More correct from Spinx's behavior: If your document describes only one command, you should not use the documented syntax or your references will fail to work.

Solution A (quick): Make the docs more explicit (please see the PR #6228).

Solution B (change Sphinx's behavior): I guess, the best would be, if there's only one program directive, to assume it's the default program. So the form :option:`-v` would still work then. When two or more programs are present, Sphinx should give out a warning that you need to use the :option:`name -v` form.

[tk0miya]

I think Solution A is not correct. The program name for :option: role is optional. With program directive, you don't need to specify it:

Before program directive, :option:`-v` searches ``-v`` option outside of program directive.
This does not match ``-v`` option for ``ls`` command.

You need to give command name explicitly like :options:`ls -v` here.

.. program:: ls

After program directive, :option:`-v` searches ``-v`` option of ``ls``. It is same as :option:`ls -v`.

So I feel #6228's fix is too much.

[tk0miya]

+0 for Solution B: I prefer this idea. But it is a bit hard to do this because Sphinx does not remember how many program are defined in document.

[buzz]

OK. Solution B is preferable. I agree. Until this is fixed, I'd go for updating the docs as the current state is misleading.