Skip to content

[3.9] bpo-40204: Allow pre-Sphinx 3 syntax in the doc (GH-21844) #21901

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
Merged
merged 7 commits into from
Aug 19, 2020
Merged

[3.9] bpo-40204: Allow pre-Sphinx 3 syntax in the doc (GH-21844) #21901

merged 7 commits into from
Aug 19, 2020

Conversation

vstinner
Copy link
Member

@vstinner vstinner commented Aug 17, 2020 •
edited by bedevere-bot
Loading

@vstinner
bpo-40204: Allow pre-Sphinx 3 syntax in the doc (GH-21844)
f904fec 
Enable Sphinx 3.2 "c_allow_pre_v3" option and disable the
c_warn_on_allowed_pre_v3 option to make the documentation compatible
with Sphinx 2 and Sphinx 3.

(cherry picked from commit 423e77d)
@vstinner
bpo-40204: Fix Sphinx sytanx in howto/instrumentation.rst (GH-21858)
244fa3f 
Use generic '.. object::' to declare markers, rather than abusing
'..  c:function::' which fails on Sphinx 3.

(cherry picked from commit 43577c0)
@vstinner
bpo-40204: Fix duplicates in the documentation (GH-21857)
b1001f5 
Fix two Sphinx 3 issues:

Doc/c-api/buffer.rst:304: WARNING: Duplicate C declaration, also defined in 'c-api/buffer'.
Declaration is 'PyBUF_ND'.

Doc/c-api/unicode.rst:1603: WARNING: Duplicate C declaration, also defined in 'c-api/unicode'.
Declaration is 'PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)'.

(cherry picked from commit 46d10b1)
@vstinner
bpo-40204: Add :noindex: in the documentation (GH-21859)
f9bb13b 
Add :noindex: to duplicated documentation to fix "duplicate object
description" errors.

For example, fix this Sphinx 3 issue:

Doc/library/configparser.rst:1146: WARNING: duplicate object
description of configparser.ConfigParser.optionxform, other instance
in library/configparser, use :noindex: for one of them

(cherry picked from commit d3ded08)
@vstinner
bpo-40204, doc: Fix syntax of C variables (GH-21846)
bb53849 
For example, fix the following Sphinx 3 errors:

Doc/c-api/buffer.rst:102: WARNING: Error in declarator or parameters
Invalid C declaration: Expected identifier in nested name. [error at 5]
  void \*obj
  -----^

Doc/c-api/arg.rst:130: WARNING: Unparseable C cross-reference: 'PyObject*'
Invalid C declaration: Expected end of definition. [error at 8]
  PyObject*
  --------^

The modified documentation is compatible with Sphinx 2 and Sphinx 3.

(cherry picked from commit 474652f)
@vstinner
bpo-40204: Fix reference to terms in the doc (GH-21865)
8d45139 
Sphinx 3 requires to refer to terms with the exact case.

For example, fix the Sphinx 3 warning:

Doc/library/pkgutil.rst:71: WARNING: term Loader not found in case
sensitive match.made a reference to loader instead.

(cherry picked from commit bb0b085)
@vstinner
bpo-40204: Fix duplicated productionlist names in the doc (GH-21900)
78e915c 
Sphinx 3 disallows having more than one productionlist markup with
the same name. Simply remove names in this case, since names are not
shown anyway. For example, fix the Sphinx 3 warning:

Doc/reference/introduction.rst:96: duplicate token description
of *:name, other instance in reference/expressions

(cherry picked from commit 1abeda8)
@vstinner
Copy link
Member Author

cc @hroncok ;-)

@hroncok
Copy link
Contributor

hroncok commented Aug 17, 2020

Thank you. Shall I test it in Fedora?

@vstinner
Copy link
Member Author

Thank you. Shall I test it in Fedora?

It's not needed.

Before backporting changes, I checked in the master branch that the documentation is still rendered properly with Sphinx 2 at https://docs.python.org/dev/ I tested manually in a virtual environment that the documentation builds without warnings in 3.9 (this PR) and master branches: the documentation is built with -W (treat warnings as errors).

@vstinner
Copy link
Member Author

@ambv @pablogsal: This change is not a bug fix, but more like a feature: support Sphinx 3. I would like to merge it into the 3.9 branch, but it can wait after 3.9.0 final. Can I merge it now? I never know if changes after RC1 after cherry-picked in a release branch, or if you use directly the 3.9 branch for releases between RC1 and the final release.

@vstinner
Copy link
Member Author

cc @doko42

@ambv
Copy link
Contributor

ambv commented Aug 19, 2020

If there isn't a flurry of commits into 3.9 I'd rather avoid cherry-picking because it makes it harder to merge back post-release. In this particular case, since this is documentation, I think this is allowed.

@vstinner vstinner merged commit 8f88190 into python:3.9 Aug 19, 2020
@vstinner vstinner deleted the sphinx3_39 branch August 19, 2020 17:25
@vstinner
Copy link
Member Author

vstinner commented Aug 19, 2020 •
edited
Loading

In this particular case, since this is documentation, I think this is allowed.

Thanks, I merged my PR.

vstinner added a commit that referenced this pull request Aug 20, 2020
@vstinner
bpo-40204: Allow pre-Sphinx 3 syntax in the doc (GH-21844) (GH-21901) (…
7d0fef5 
…GH-21928)

* bpo-40204: Allow pre-Sphinx 3 syntax in the doc (GH-21844)

Enable Sphinx 3.2 "c_allow_pre_v3" option and disable the
c_warn_on_allowed_pre_v3 option to make the documentation compatible
with Sphinx 2 and Sphinx 3.

(cherry picked from commit 423e77d)

* bpo-40204: Fix Sphinx sytanx in howto/instrumentation.rst (GH-21858)

Use generic '.. object::' to declare markers, rather than abusing
'..  c:function::' which fails on Sphinx 3.

(cherry picked from commit 43577c0)

* bpo-40204: Fix duplicates in the documentation (GH-21857)

Fix two Sphinx 3 issues:

Doc/c-api/buffer.rst:304: WARNING: Duplicate C declaration, also defined in 'c-api/buffer'.
Declaration is 'PyBUF_ND'.

Doc/c-api/unicode.rst:1603: WARNING: Duplicate C declaration, also defined in 'c-api/unicode'.
Declaration is 'PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors)'.

(cherry picked from commit 46d10b1)

* bpo-40204: Add :noindex: in the documentation (GH-21859)

Add :noindex: to duplicated documentation to fix "duplicate object
description" errors.

For example, fix this Sphinx 3 issue:

Doc/library/configparser.rst:1146: WARNING: duplicate object
description of configparser.ConfigParser.optionxform, other instance
in library/configparser, use :noindex: for one of them

(cherry picked from commit d3ded08)

* bpo-40204, doc: Fix syntax of C variables (GH-21846)

For example, fix the following Sphinx 3 errors:

Doc/c-api/buffer.rst:102: WARNING: Error in declarator or parameters
Invalid C declaration: Expected identifier in nested name. [error at 5]
  void \*obj
  -----^

Doc/c-api/arg.rst:130: WARNING: Unparseable C cross-reference: 'PyObject*'
Invalid C declaration: Expected end of definition. [error at 8]
  PyObject*
  --------^

The modified documentation is compatible with Sphinx 2 and Sphinx 3.

(cherry picked from commit 474652f)

* bpo-40204: Fix reference to terms in the doc (GH-21865)

Sphinx 3 requires to refer to terms with the exact case.

For example, fix the Sphinx 3 warning:

Doc/library/pkgutil.rst:71: WARNING: term Loader not found in case
sensitive match.made a reference to loader instead.

(cherry picked from commit bb0b085)

* bpo-40204: Fix duplicated productionlist names in the doc (GH-21900)

Sphinx 3 disallows having more than one productionlist markup with
the same name. Simply remove names in this case, since names are not
shown anyway. For example, fix the Sphinx 3 warning:

Doc/reference/introduction.rst:96: duplicate token description
of *:name, other instance in reference/expressions

(cherry picked from commit 1abeda8)
(cherry picked from commit 8f88190)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@ambv ambv ambv approved these changes

@ethanfurman ethanfurman Awaiting requested review from ethanfurman ethanfurman is a code owner

@rhettinger rhettinger Awaiting requested review from rhettinger rhettinger is a code owner

@tiran tiran Awaiting requested review from tiran tiran is a code owner

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
5 participants
@vstinner @hroncok @ambv @the-knights-who-say-ni @bedevere-bot