Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Support programs with options that differ only by case or punctuation #3366

Closed
zygoloid opened this issue Jan 24, 2017 · 4 comments
Closed

Support programs with options that differ only by case or punctuation #3366

zygoloid opened this issue Jan 24, 2017 · 4 comments
Assignees
@shimizukawa @tk0miya
Labels
domains:std markup type:bug
Milestone
1.5.3

Comments

@zygoloid
Copy link

Subject: Support programs with options that differ only by case or punctuation

Problem

  • clang, an open-source C/C++/... compiler, supports lots of options, and in some cases the options differ only by punctuation (-ObjC and -ObjC++ mean different things, as do -I and -I-); in other cases, options contain only punctuation (/?). Sphinx does not support documenting such options.

Procedure to reproduce the problem

.. option:: -ObjC

Description of option ``-ObjC``.

.. option:: -ObjC++

Description of option ``-ObjC++``.

Error logs / results

ClangCommandLineReference.rst:9: SEVERE: Duplicate ID: "cmdoption-clang-ObjC".

Expected results

Produce distinct IDs for distinct flags. Do not assume that punctuation can be stripped. Support options containing only punctuation. Either that, or provide a mechanism to override the ID generated for a particular option name.

Reproducible project / your project

Environment info

  • Python version: 2.7.6
  • Sphinx version: 1.2.2
@tk0miya tk0miya added this to the 1.5.3 milestone Jan 26, 2017
@tk0miya
Copy link
Member

tk0miya commented Jan 26, 2017

In my short investigation:
The option directive uses following regexp to parse given option:

option_desc_re = re.compile(r'((?:/|--|-|\+)?[-\.?@#_a-zA-Z0-9]+)(=?\s*.*)')

At present, it does not contain + sign. So -ObjC++ is recognized as -ObjC option having ++ argument. Then it is a cause of the duplication warning.
To fix this, I would add + sign to the regexp. In my local, it works fine.

BTW, now we can use only -.?@#_ signs for option name. This means the following characters could not be used:
!"#$%&()*+,/:;<>[\]^{|}~, ` (back quote) and any non ASCII characters.
Is this intended?
I feel we should reconsider these definition.

@shimizukawa any ideas?

@tk0miya tk0miya assigned tk0miya and shimizukawa and unassigned tk0miya Jan 26, 2017
@tk0miya
Copy link
Member

tk0miya commented Jan 26, 2017

Side note:
I don't list up = character to the unsupported signs for option name with intent.
It is used for a delimiter of option name and argument. So it means Sphinx cannot use = sign for an option name. I think it is a restriction of Sphinx.

@shimizukawa
Copy link
Member

IMO, it is nice if every string.punctuation characters were accepted exclude = char.

tk0miya added a commit that referenced this issue Feb 14, 2017
@tk0miya
option directive also allows all punctuations for the option name (re…
baa065f 
…fs: #3366)
@tk0miya
Copy link
Member

tk0miya commented Feb 14, 2017

Fixed at b9bba67 and baa065f.
Only + sign is allowed in stable branch to keep compatibility. It will be released as 1.5.3.
And all punctuations are allowed in master branch.

Thank you for reporting.

qemu-deploy pushed a commit to qemu/qemu that referenced this issue Apr 14, 2020
@pm215
docs: Require Sphinx 1.6 or better
bf3f857 
Versions of Sphinx older than 1.6 can't build all of our documentation,
because they are too picky about the syntax of the argument to the
option:: directive; see Sphinx bugs #646, #3366:

  sphinx-doc/sphinx#646
  sphinx-doc/sphinx#3366

Trying to build with a 1.4.x Sphinx fails with
 docs/system/images.rst:4: SEVERE: Duplicate ID: "cmdoption-qcow2-arg-encrypt"
and a 1.5.x Sphinx fails with
 docs/system/invocation.rst:544: WARNING: Malformed option description '[enable=]PATTERN', should look like "opt", "-opt
args", "--opt args", "/opt args" or "+opt args"

Update our needs_sphinx setting to indicate that we require at least
1.6.  This will allow configure to fall back to "don't build the
docs" rather than causing the build to fail entirely, which is
probably what most users building on a host old enough to have such
an old Sphinx would want; if they do want the docs then they'll have
a useful indication of what they need to do (upgrade Sphinx!) rather
than a confusing error message.

In theory our distro support policy would suggest that we should
support building on the Sphinx shipped in those distros, but:
 * EPEL7 has Sphinx 1.2.3 (which we've never supported!)
 * Debian Stretch has Sphinx 1.4.8

Trying to get our docs to work with Sphinx 1.4 is not tractable
for the 5.0 release and I'm not sure it's worthwhile effort anyway;
at least with this change the build as a whole now succeeds.

Thanks to John Snow for doing the investigation and testing to
confirm what Sphinx versions fail in what ways and what distros
shipped what.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
gorbak25 pushed a commit to gorbak25/qemu that referenced this issue Apr 28, 2020
@pm215 @gorbak25
docs: Require Sphinx 1.6 or better
c6207b3 
Versions of Sphinx older than 1.6 can't build all of our documentation,
because they are too picky about the syntax of the argument to the
option:: directive; see Sphinx bugs #646, #3366:

  sphinx-doc/sphinx#646
  sphinx-doc/sphinx#3366

Trying to build with a 1.4.x Sphinx fails with
 docs/system/images.rst:4: SEVERE: Duplicate ID: "cmdoption-qcow2-arg-encrypt"
and a 1.5.x Sphinx fails with
 docs/system/invocation.rst:544: WARNING: Malformed option description '[enable=]PATTERN', should look like "opt", "-opt
args", "--opt args", "/opt args" or "+opt args"

Update our needs_sphinx setting to indicate that we require at least
1.6.  This will allow configure to fall back to "don't build the
docs" rather than causing the build to fail entirely, which is
probably what most users building on a host old enough to have such
an old Sphinx would want; if they do want the docs then they'll have
a useful indication of what they need to do (upgrade Sphinx!) rather
than a confusing error message.

In theory our distro support policy would suggest that we should
support building on the Sphinx shipped in those distros, but:
 * EPEL7 has Sphinx 1.2.3 (which we've never supported!)
 * Debian Stretch has Sphinx 1.4.8

Trying to get our docs to work with Sphinx 1.4 is not tractable
for the 5.0 release and I'm not sure it's worthwhile effort anyway;
at least with this change the build as a whole now succeeds.

Thanks to John Snow for doing the investigation and testing to
confirm what Sphinx versions fail in what ways and what distros
shipped what.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Aug 30, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees

@shimizukawa shimizukawa

@tk0miya tk0miya

Labels
domains:std markup type:bug
Projects
None yet
Milestone
1.5.3
Development

No branches or pull requests
3 participants
@shimizukawa @zygoloid @tk0miya