bpo-38387: Formally document PyDoc_STRVAR and PyDoc_STR macros #16607

bsolomon1124 · 2019-10-06T23:38:54Z

Adds a short description of PyDoc_STRVAR and PyDoc_STR to "Useful macros" section of C-API docs.

Currently, there is one lone mention in the C-API reference, despite the fact that PyDoc_STRVAR is ubiquitous to Modules/.

Additionally, this properly uses c:macro within c-api/module.html to link.

https://bugs.python.org/issue38387

Doc/c-api/intro.rst

Misc/NEWS.d/next/Documentation/2019-10-06-23-44-15.bpo-38387.fZoq0S.rst

Doc/c-api/intro.rst

aeros · 2019-10-07T06:21:41Z

@bsolomon1124 Thanks for the PR. I think it's certainly worthwhile to document the macro, especially considering how common it's utilized.

But, I'm in agreement with the changes recommended by @ammaraskar: removing the description of the internals and adding a brief example.

bsolomon1124 · 2019-10-07T06:41:23Z

All the suggested changes here make sense and I'll add them when I have a chance.

I also think it might be worth mentioning the stated use of these macros:

Use the PyDoc_STR() or PyDoc_STRVAR() macro for docstrings to support building Python without docstrings (./configure --without-doc-strings).

https://www.python.org/dev/peps/pep-0007/#documentation-strings

Do you think that is also extraneous detail @aeros167 @ammaraskar ?

aeros · 2019-10-07T07:26:43Z

I think that might be worth adding, but I would recommend linking to the PEP itself using an inline Sphinx role:

Use the ``PyDoc_STR()`` or ``PyDoc_STRVAR()`` macro for docstrings to support
building Python without docstrings, as specified in :pep:`7`.

This provides readers a location for further information and means that we don't have to update this section if the syntax ever changes for ./configure --without-doc-string.

But, if it is decided that the exact syntax should be specified in the docs, inline codeblocks should be used instead of parentheses. This also applies to the macros, optionally Sphinx roles can be used for those (they're not needed if the definition for the macro is immediately nearby or within its own definition, as the link would be fairly pointless).

Doc/c-api/intro.rst

bsolomon1124 · 2020-01-27T00:07:05Z

@ammaraskar I've added a section for PyDoc_STR also here. Appreciate if you have time for another review.

Doc/c-api/intro.rst

aeros · 2020-01-27T05:08:24Z

While I think it's probably okay in this case, I'd generally recommend against including additional sections in a PR that are outside of the scope of the original issue that it's attached to. The scope of this issue was specifically adding documentation for PyDoc_STRVAR.

Going outside of the scope can substantially to the required review time, particularly if you already have received several reviews on the PR. It may not seem like much in this case, but it can really add up when you consider the total volume of open PRs and our limited review time (it's mostly volunteer-driven).

An exception to the above is if you specifically ask a core developer about it and they approve of including additional related changes in the PR. There's also the option of simply opening a second PR and attaching it to the same issue; assuming they're both related.

miss-islington · 2020-04-27T02:32:08Z

Thanks @bsolomon1124 for the PR, and @zware for merging it 🌮🎉.. I'm working now to backport this PR to: 3.7.
🐍🍒⛏🤖

miss-islington · 2020-04-27T02:32:08Z

Thanks @bsolomon1124 for the PR, and @zware for merging it 🌮🎉.. I'm working now to backport this PR to: 3.8.
🐍🍒⛏🤖

miss-islington · 2020-04-27T02:32:16Z

Sorry, @bsolomon1124 and @zware, I could not cleanly backport this to 3.7 due to a conflict.
Please backport using cherry_picker on command line.
cherry_picker b54e46cb57ebac5c525a9a6be241412cd57bc935 3.7

miss-islington · 2020-04-27T02:32:18Z

Sorry @bsolomon1124 and @zware, I had trouble checking out the 3.8 backport branch.
Please backport using cherry_picker on command line.
cherry_picker b54e46cb57ebac5c525a9a6be241412cd57bc935 3.8

bedevere-bot · 2020-04-27T02:35:03Z

GH-19727 is a backport of this pull request to the 3.8 branch.

…ythonGH-16607) Adds a short description of `PyDoc_STRVAR` and `PyDoc_STR` to "Useful macros" section of C-API docs. Currently, there is [one lone mention](https://docs.python.org/3/c-api/module.html?highlight=pydoc_strvarGH-c.PyModuleDef) in the C-API reference, despite the fact that `PyDoc_STRVAR` is ubiquitous to `Modules/`. Additionally, this properly uses `c:macro` within `Doc/c-api/module.rst` to link. (cherry picked from commit b54e46c) Co-authored-by: Brad Solomon <brad.solomon.1124@gmail.com>

…ythonGH-16607) Adds a short description of `PyDoc_STRVAR` and `PyDoc_STR` to "Useful macros" section of C-API docs. Currently, there is [one lone mention](https://docs.python.org/3/c-api/module.html?highlight=pydoc_strvarGH-c.PyModuleDef) in the C-API reference, despite the fact that `PyDoc_STRVAR` is ubiquitous to `Modules/`. Additionally, this properly uses `c:macro` within `Doc/c-api/module.rst` to link.. (cherry picked from commit b54e46c) Co-authored-by: Brad Solomon <brad.solomon.1124@gmail.com>

bedevere-bot · 2020-04-27T02:37:31Z

GH-19728 is a backport of this pull request to the 3.7 branch.

…H-16607) (GH-19727) Adds a short description of `PyDoc_STRVAR` and `PyDoc_STR` to "Useful macros" section of C-API docs. Currently, there is [one lone mention](https://docs.python.org/3/c-api/module.html?highlight=pydoc_strvarGH-c.PyModuleDef) in the C-API reference, despite the fact that `PyDoc_STRVAR` is ubiquitous to `Modules/`. Additionally, this properly uses `c:macro` within `Doc/c-api/module.rst` to link. (cherry picked from commit b54e46c) Authored-by: Brad Solomon <brad.solomon.1124@gmail.com>

…H-16607) (GH-19728) Adds a short description of `PyDoc_STRVAR` and `PyDoc_STR` to "Useful macros" section of C-API docs. Currently, there is [one lone mention](https://docs.python.org/3/c-api/module.html?highlight=pydoc_strvarGH-c.PyModuleDef) in the C-API reference, despite the fact that `PyDoc_STRVAR` is ubiquitous to `Modules/`. Additionally, this properly uses `c:macro` within `Doc/c-api/module.rst` to link.. (cherry picked from commit b54e46c) Co-authored-by: Brad Solomon <brad.solomon.1124@gmail.com>

* 'master' of github.com:python/cpython: (2949 commits) Add files in tests/test_peg_generator to the install target lists (pythonGH-19723) bpo-40398: Fix typing.get_args() for special generic aliases. (pythonGH-19720) bpo-40348: Fix typos in the programming FAQ (pythonGH-19729) bpo-38387: Formally document PyDoc_STRVAR and PyDoc_STR macros (pythonGH-16607) bpo-40401: Remove duplicate pyhash.h include from pythoncore.vcxproj (pythonGH-19725) bpo-40387: Improve queue join() example. (pythonGH-19724) bpo-40396: Support GenericAlias in the typing functions. (pythonGH-19718) Fix typo in Lib/typing.py (pythonGH-19717) Fix typo in object.__format__ docs (pythonGH-19504) bpo-40275: Avoid importing logging in test.support (pythonGH-19601) bpo-40275: Avoid importing socket in test.support (pythonGH-19603) bpo-40275: Avoid importing asyncio in test.support (pythonGH-19600) bpo-40279: Add some error-handling to the module initialisation docs example (pythonGH-19705) closes bpo-40385: Remove Tools/scripts/checkpyc.py (pythonGH-19709) bpo-40334: Add What's New sections for PEP 617 and PEP 585 (pythonGH-19704) bpo-40340: Separate examples more clearly in the programming FAQ (pythonGH-19688) bpo-40360: Deprecate lib2to3 module in light of PEP 617 (pythonGH-19663) bpo-40334: Rewrite test_c_parser to avoid memory leaks (pythonGH-19694) bpo-38061: subprocess uses closefrom() on FreeBSD (pythonGH-19697) bpo-38061: os.closerange() uses closefrom() on FreeBSD (pythonGH-19696) ...

the-knights-who-say-ni added the CLA signed label Oct 6, 2019

bedevere-bot added docs Documentation in the Doc dir awaiting review labels Oct 6, 2019

bsolomon1124 changed the title ~~Formally document PyDoc_STRVAR macro~~ bpo-38387: Formally document PyDoc_STRVAR macro Oct 6, 2019

ammaraskar requested changes Oct 7, 2019

View reviewed changes

Doc/c-api/intro.rst Outdated Show resolved Hide resolved

Doc/c-api/intro.rst Outdated Show resolved Hide resolved

Misc/NEWS.d/next/Documentation/2019-10-06-23-44-15.bpo-38387.fZoq0S.rst Outdated Show resolved Hide resolved

bedevere-bot added awaiting core review and removed awaiting review labels Oct 7, 2019

ghost reviewed Oct 7, 2019

View reviewed changes

Doc/c-api/intro.rst Outdated Show resolved Hide resolved

aeros reviewed Oct 7, 2019

View reviewed changes

Doc/c-api/intro.rst Show resolved Hide resolved

aeros approved these changes Oct 8, 2019

View reviewed changes

ammaraskar reviewed Oct 10, 2019

View reviewed changes

Doc/c-api/intro.rst Outdated Show resolved Hide resolved

bsolomon1124 and others added 5 commits January 26, 2020 17:35

Formally document PyDoc_STRVAR macro

b68431c

📜🤖 Added by blurb_it.

7d95103

Modify PyDoc_STRVAR example; mention PEP 7

097553f

Use proper RST in news entry

644b8ae

Document PyDoc_STR alongside PyDoc_STRVAR

c05b5ba

bsolomon1124 force-pushed the document-PyDoc_STRVAR branch from 12c36d6 to c05b5ba Compare January 26, 2020 23:30

aeros reviewed Jan 27, 2020

View reviewed changes

Doc/c-api/intro.rst Show resolved Hide resolved

bsolomon1124 changed the title ~~bpo-38387: Formally document PyDoc_STRVAR macro~~ bpo-38387: Formally document PyDoc_STRVAR and PyDoc_STR macros Jan 27, 2020

zware approved these changes Apr 27, 2020

View reviewed changes

bedevere-bot added awaiting merge and removed awaiting core review labels Apr 27, 2020

zware merged commit b54e46c into python:master Apr 27, 2020

bedevere-bot removed the awaiting merge label Apr 27, 2020

zware added the needs backport to 3.7 label Apr 27, 2020

zware added the needs backport to 3.8 label Apr 27, 2020

miss-islington assigned zware Apr 27, 2020

bedevere-bot removed the needs backport to 3.8 label Apr 27, 2020

bedevere-bot removed the needs backport to 3.7 label Apr 27, 2020

bsolomon1124 deleted the document-PyDoc_STRVAR branch April 27, 2020 11:11

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

bpo-38387: Formally document PyDoc_STRVAR and PyDoc_STR macros #16607

bpo-38387: Formally document PyDoc_STRVAR and PyDoc_STR macros #16607

bsolomon1124 commented Oct 6, 2019 •

edited

Loading

aeros commented Oct 7, 2019 •

edited

Loading

bsolomon1124 commented Oct 7, 2019 •

edited

Loading

aeros commented Oct 7, 2019 •

edited

Loading

bsolomon1124 commented Jan 27, 2020

aeros commented Jan 27, 2020 •

edited

Loading

miss-islington commented Apr 27, 2020

miss-islington commented Apr 27, 2020

miss-islington commented Apr 27, 2020

miss-islington commented Apr 27, 2020

bedevere-bot commented Apr 27, 2020

bedevere-bot commented Apr 27, 2020

bpo-38387: Formally document PyDoc_STRVAR and PyDoc_STR macros #16607

bpo-38387: Formally document PyDoc_STRVAR and PyDoc_STR macros #16607

Conversation

bsolomon1124 commented Oct 6, 2019 • edited Loading

aeros commented Oct 7, 2019 • edited Loading

bsolomon1124 commented Oct 7, 2019 • edited Loading

aeros commented Oct 7, 2019 • edited Loading

bsolomon1124 commented Jan 27, 2020

aeros commented Jan 27, 2020 • edited Loading

miss-islington commented Apr 27, 2020

miss-islington commented Apr 27, 2020

miss-islington commented Apr 27, 2020

miss-islington commented Apr 27, 2020

bedevere-bot commented Apr 27, 2020

bedevere-bot commented Apr 27, 2020

bsolomon1124 commented Oct 6, 2019 •

edited

Loading

aeros commented Oct 7, 2019 •

edited

Loading

bsolomon1124 commented Oct 7, 2019 •

edited

Loading

aeros commented Oct 7, 2019 •

edited

Loading

aeros commented Jan 27, 2020 •

edited

Loading