[sphinx-users] Warnings with the "option" role ("unknown option")

[F. KATS]

Hello,

I have a document that used to compile fine with no warnings with previous
Sphinx versions (approximately 6 months ago). With Sphinx 1.3.5, I get many
warnings that worry me because then I risk missing more serious errors.
Example of such warnings:

FILE:LINE: WARNING: unknown option: --file
FILE:LINE: WARNING: unknown option: --title

In the .rst sources, these correspond to text such as "unlike the
:option:`--title` option ..."). I think this warning is due to the fact
that my documents don't mention this --title option in any "option"
directive. But such options belong to an external program, not to the
library I am documenting, therefore it would be unreasonable to document
these options in my library's documentation.

Looking at the Sphinx Manual on the subject, I saw that in some places,
they use syntax like :option:`rm -r`. I tried it here, but it doesn't solve
the problem. Instead of:

WARNING: unknown option: --title

using :option:`dialog --title` gets me warnings of this kind:

WARNING: unknown option: dialog --title

Worse, in the resulting output (I checked the HTML output), I get "dialog
--title" instead of just the option name, "--title". This renders the
sentences much less clear, therefore IMHO this only is a bug that should be
fixed, short of rendering the "option" role pretty much useless... If the
documentation writer wants to have the program name precede the option, he
can easily add it. But if this is done automatically by Sphinx, how can he
get rid of it when it is undesirable?

What is the best way to format these options "soft references" (i.e.,
without any target link) in the text?

Thank you very much for your help and for the great software!

Regards,

Florent

[Takayuki Shimizukawa]

Hi Florent,

I thinks it relates to https://github.com/sphinx-doc/sphinx/issues/2229
We'll check the correct behavior. If you have chance, please comment to the
ticket.
Anyhow, thanks for your reporting!

Regards,
--
Takayuki SHIMIZUKAWA
http://about.me/shimizukawa

Post by F. KATS
Hello,
I have a document that used to compile fine with no warnings with previous
Sphinx versions (approximately 6 months ago). With Sphinx 1.3.5, I get many
warnings that worry me because then I risk missing more serious errors.
FILE:LINE: WARNING: unknown option: --file
FILE:LINE: WARNING: unknown option: --title
In the .rst sources, these correspond to text such as "unlike the
:option:`--title` option ..."). I think this warning is due to the fact
that my documents don't mention this --title option in any "option"
directive. But such options belong to an external program, not to the
library I am documenting, therefore it would be unreasonable to document
these options in my library's documentation.
Looking at the Sphinx Manual on the subject, I saw that in some places,
they use syntax like :option:`rm -r`. I tried it here, but it doesn't
WARNING: unknown option: --title
WARNING: unknown option: dialog --title
Worse, in the resulting output (I checked the HTML output), I get "dialog
--title" instead of just the option name, "--title". This renders the
sentences much less clear, therefore IMHO this only is a bug that should be
fixed, short of rendering the "option" role pretty much useless... If the
documentation writer wants to have the program name precede the option, he
can easily add it. But if this is done automatically by Sphinx, how can he
get rid of it when it is undesirable?
What is the best way to format these options "soft references" (i.e.,
without any target link) in the text?
Thank you very much for your help and for the great software!
Regards,
Florent
--
You received this message because you are subscribed to the Google Groups
"sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an
Visit this group at https://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.

[F. KATS]

Hi Takayuki,

Many thanks for your answer! Indeed, issue 2229 seems related to the
problem I encountered. I have added a comment there.

Regards