Avoid warnings about missing CLI options when building documentation

[vadmium]

BPO	26638
Nosy	@birkenfeld, @terryjreedy, @vstinner, @ezio-melotti, @merwok, @vadmium, @zware
Files	doc-warnings.patch doc-warnings.v2.patch disable-warning.patch doc-warnings.v3.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2016-10-30.06:34:21.803>
created_at = <Date 2016-03-25.04:49:39.924>
labels = ['3.7', 'docs']
title = 'Avoid warnings about missing CLI options when building documentation'
updated_at = <Date 2016-10-30.06:34:21.801>
user = 'https://github.com/vadmium'

bugs.python.org fields:

activity = <Date 2016-10-30.06:34:21.801>
actor = 'martin.panter'
assignee = 'docs@python'
closed = True
closed_date = <Date 2016-10-30.06:34:21.803>
closer = 'martin.panter'
components = ['Documentation']
creation = <Date 2016-03-25.04:49:39.924>
creator = 'martin.panter'
dependencies = []
files = ['42282', '42481', '42482', '43889']
hgrepos = []
issue_num = 26638
keywords = ['patch']
message_count = 17.0
messages = ['262401', '262592', '263405', '263434', '263539', '263547', '263548', '271335', '273588', '273591', '273597', '273656', '273674', '273747', '279676', '279708', '279711']
nosy_count = 10.0
nosy_names = ['georg.brandl', 'terry.reedy', 'vstinner', 'ezio.melotti', 'eric.araujo', 'SilentGhost', 'docs@python', 'python-dev', 'martin.panter', 'zach.ware']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue26638'
versions = ['Python 2.7', 'Python 3.5', 'Python 3.6', 'Python 3.7']

[vadmium]

Defeat many warnings and related fixes building documentation

• Mask various CLI options with exclamation marks (!)
• Correct link to CLI section in zipapp
• Make CLI section label in timeit less ambiguous

The following warnings from unittest remain. Ideally they should be linked to the Python CLI documentation, but this does not seem possible because the “unittest” documentation defines its own CLI options.

Doc/library/unittest.rst:1965: WARNING: unknown option: -Wd
Doc/library/unittest.rst:1965: WARNING: unknown option: -Wa
Doc/library/unittest.rst:2051: WARNING: unknown option: -W

[vadmium]

FTR the warnings that I am fixing were apparently enabled in Sphinx 1.3.4, reverted in 1.3.6, and added in 1.4.

[vstinner]

FTR the warnings that I am fixing were apparently enabled in Sphinx 1.3.4, reverted in 1.3.6, and added in 1.4.

Would it be possible to turn off the warning?

Doc/using/cmdline.py uses ".. cmdoption::". If we cannot turn off the warning on option, maybe we should use a new :cmdoption:`xxx` which wouldn't emit a warning?

I'm not strongly opposed to doc-warnings.patch.

I understand that Sphinx expects the exact option, for example -W, whereas the doc uses option with parameter like -Wd. Sphinx is unable to link to the option.

Maybe we need something like :cmdoption:`-Wd <-W>`: display -Wd but link to -W?

[vadmium]

I’m not an expert on Sphinx. Maybe <http://www.sphinx-doc.org/en/stable/config.html#confval-suppress_warnings\> could help with disabling these warnings. Considering there are so many false positives, it might be best to disable the warning. Though my patch does have a few genuine improvements as well.

I already used the :option:`-Wd <-W>` syntax in some cases; see Doc/library/warnings.rst for example. The problem in unittest.rst is I think Sphinx is trying to find a -W option defined within unittest.rst (with the unittest --buffer etc options), rather than the main Python options from using/cmdline.rst.

[python-dev]

New changeset 23a884c32a39 by Martin Panter in branch '3.5':
Issue bpo-26638: Fix links to some CLI options and section headings
https://hg.python.org/cpython/rev/23a884c32a39

New changeset 68b84643dffd by Martin Panter in branch 'default':
Issue bpo-26638: Merge link fixes from 3.5
https://hg.python.org/cpython/rev/68b84643dffd

New changeset 3e0321584f23 by Martin Panter in branch '2.7':
Issue bpo-26638: Fix links to some CLI options
https://hg.python.org/cpython/rev/3e0321584f23

[vadmium]

I committed the parts of my patch that improve real links in the end result.

doc-warnings.v2.patch has the remaining changes which add exclamation marks to mask undefined options.

[vadmium]

This patch disables the warning, but I tend to think it is not a good long-term solution.

[python-dev]

New changeset 3996dd17ca21 by Martin Panter in branch '3.5':
Issue bpo-26638: Don’t link 2to3 -l option to the tarfile -l option
https://hg.python.org/cpython/rev/3996dd17ca21

New changeset d7cbaaba59e8 by Martin Panter in branch 'default':
Issue bpo-26638: Merge CLI link fix from 3.5
https://hg.python.org/cpython/rev/d7cbaaba59e8

[terryjreedy]

I built the 3.5 docs on Win10 with Sphinx 1.3.3 and corresponding dependencies and got a new warning as a result of 8ba0000c90be for bpo-26462:
F:\Python\dev\36\Doc\whatsnew\3.2.rst:2063: WARNING: Pygments lexer name 'doscon' is not known

Thinking the problem was an out-of-date pygments module, I updated sphinx and dependencies (to 1.4.6, etc). I was right that updating pygments fixed the warning above, but now I get 140 warnings!!!

4 are from the reading phase for configparser.rst. The first:

F:\Python\dev\35\Doc\library\configparser.rst:240: WARNING: Could not lex literal_block as "ini". Highlighting skipped.

I presume this could be fixed, but I don't know how.

136 are about "<path: WARNING: unknown option: -x."

Sphinx, at least with how we use it, and the Python docs are out of sync here. I think we need more eyes on this.

"This patch disables the warning," ??? Not here.

" but I tend to think it is not a good long-term solution."

Printing 136 warnings is also not a good solution. I rebuilt the docs locally because I was planning to patch a misspelling I found while reading the doc. Looking in a list of several pages for a warning I might have caused is failure-prone and no fun. In the Windows console, the page-up and page-down keys do not page up and down. To not miss anything, I would have to carefully use a mouse wheel or scrollbar clicks.

I am building with "sphinx-build -bhtml . build/html" is a .bat file. Is there anything I can add to suppress only 'unknown option' warnings?

[zware]

Terry: for now, you can downgrade Sphinx to 1.3.6 as it is known to build with no warnings (that's the version the Docs buildbot currently uses).

[terryjreedy]

Only 138 warnings with 2.7.

Zack, how do I downgrade. I examined the result of pip install -h but cannot see how. I presume that 'sphinx' and '1.3.6' should be combined into a '<requirement specifier>' but this latter is not defined and the things I tried, including the output format of 'pip list' did not work.

Does anything else need to be downgraded?

[zware]

The syntax is <pip> install "<package><comparison><version>", so in this case 'pip install "Sphinx==1.3.6"(orpip install "Sphinx<1.4"`) should do it for you. That ought to also take care of downgrading any other packages that need it (though I don't think there are any), or at least tell you which ones should be downgraded and to what.

I'm not sure why there are both pip list and pip freeze, but pip freeze is the one that outputs usable syntax for a requirement specifier.

[terryjreedy]

Thank you, that worked -- and should have been documented in the help output. All the sphinx dependencies were inequalities, and rebuilding worked.

The devguide only says "You are expected to have installed a recent version of Sphinx on your system or in a virtualenv,". Could we add

"We currently recommend 'python -m pip install sphinx==1.3.6' as the easiest way to install and the best version for most people to install. See https://bugs.python.org/issue26638 for why."

(I am assuming that pip works on all systems, not just Windows.) The sentence finishes with "so that the Makefile can find the sphinx-build command." On Windows. this is most easily done by installing Sphinx with a Python version that was added to PATH when installed.