Skip to content

bpo-40204: Allow pre-Sphinx 3 syntax in the doc #21844

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 1 commit into from
Aug 12, 2020
Merged

bpo-40204: Allow pre-Sphinx 3 syntax in the doc #21844

merged 1 commit into from
Aug 12, 2020

Conversation

vstinner
Copy link
Member

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

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.

https://bugs.python.org/issue40204

@vstinner
bpo-40204: Allow pre-Sphinx 3 syntax in the doc
3724655 
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.
@vstinner
Copy link
Member Author

cc @ammaraskar

@doko42 doko42 self-requested a review August 12, 2020 17:55
@doko42
Copy link
Member

doko42 commented Aug 12, 2020

this looks ok. Although it still fails to build the docs with -W enabled, as mentioned in https://bugs.python.org/msg375254

@vstinner
Copy link
Member Author

this looks ok. Although it still fails to build the docs with -W enabled, as mentioned in https://bugs.python.org/msg375254

I plan to submit following PRs to fix most of these warnings. #21846 is the first.

@vstinner vstinner merged commit 423e77d into python:master Aug 12, 2020
@vstinner vstinner deleted the sphinx3 branch August 12, 2020 19:49
@vstinner
Copy link
Member Author

Thanks for the review @doko42, I merged my PR.

@hroncok
Copy link
Contributor

hroncok commented Aug 13, 2020

@vstinner Any chance this could be backported to 3.9?

@vstinner
Copy link
Member Author

I would prefer to fix most issues in master first, and only later to backport all changes at once in 3.9.

But yes, I will try to backport Sphinx 3.2+ compatibility as far as I can.

vstinner added a commit that referenced this pull request Aug 19, 2020
@vstinner
[3.9] bpo-40204: Allow pre-Sphinx 3 syntax in the doc (GH-21844) (GH-…
8f88190 
…21901)

* 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)
This was referenced Aug 19, 2020
Closed
Merged
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)
shihai1991 pushed a commit to shihai1991/cpython that referenced this pull request Aug 20, 2020
@vstinner @shihai1991
bpo-40204: Allow pre-Sphinx 3 syntax in the doc (pythonGH-21844)
8c5a703 
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.
@stratakis
Copy link
Contributor

Thanks for the fixes Victor!

xzy3 pushed a commit to xzy3/cpython that referenced this pull request Oct 18, 2020
@vstinner
bpo-40204: Allow pre-Sphinx 3 syntax in the doc (pythonGH-21844)
7ac99f5 
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@doko42 doko42 doko42 approved these changes

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

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