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.

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

Some C struct members are not marked up in docs #97909

Open
encukou opened this issue Oct 5, 2022 · 13 comments
Open

Some C struct members are not marked up in docs #97909

encukou opened this issue Oct 5, 2022 · 13 comments
Labels
docs Documentation in the Doc dir

Comments

@encukou
Copy link
Member

encukou commented Oct 5, 2022

The members of PyMemberDef aren't marked up as members, so they can't be linked to individually.

Linked PRs

@encukou encukou added docs Documentation in the Doc dir easy labels Oct 5, 2022
@encukou
Copy link
Member Author

encukou commented Oct 12, 2022

Reserving for a student. Everyone else, please don't start on this issue this week.


You will want to click “Show Source” on the page linked in the first comment. That will take you to the place you need to edit on GitHub.

You will also want to read the Devguide, for info like how to build the documentation with your changes: https://devguide.python.org/documentation/start-documenting/

An example of how members should be documented is in PyType_Spec: https://docs.python.org/3/c-api/type.html#c.PyType_Spec

@encukou encukou removed the easy label Oct 12, 2022
@Johnny11502
Copy link
Contributor

@encukou I would like to work on this issue. Thanks for the hint!

@Johnny11502
Copy link
Contributor

@encukou Just to let you know, I did not forget about this issue and I have just been a bit busy at work this week. I will try and submit my PR tonight or tomorrow.

@Johnny11502
Copy link
Contributor

@encukou I am a bit confused about what needs to be marked up as a member under PyMemberDef. I looked at PyType_Spec and saw how PyType_Spec.name and the members that follow were documented but I do not see what would need it for this issue. Would you please be able to specify the lines or text that needs to be corrected.

@encukou
Copy link
Member Author

encukou commented Oct 17, 2022

The members (fields) are name, type, offset, etc. Currently they're defined in a table, so they don't show up when searching the docs for PyMemberDef.name (and when writing the docs, can't be linked using :c:member`PyMemberDef.name`).
The table should be converted to entries for the individual members.

@Johnny11502
Copy link
Contributor

Got it, thanks!

Johnny11502 added a commit to Johnny11502/cpython-Fork that referenced this issue Oct 19, 2022
encukou pushed a commit that referenced this issue Oct 24, 2022
@encukou encukou changed the title PyMemberDef members are not marked up PyMemberDef & PyGetSetDef members are not marked up Oct 24, 2022
@encukou
Copy link
Member Author

encukou commented Oct 24, 2022

PyGetSetDef is in the same situation, let's use this issue for that as well.

@Johnny11502
Copy link
Contributor

@encukou I can update the members of PyGetSetDef as well since it would pretty much be the same if you don't mind.

@encukou
Copy link
Member Author

encukou commented Oct 24, 2022

Sounds good, thanks!

@encukou
Copy link
Member Author

encukou commented Oct 24, 2022

Please do not convert the T_* macros (T_SHORT etc.), though. I'm making bigger changes in that area.

@encukou encukou closed this as completed Nov 3, 2022
@encukou encukou changed the title PyMemberDef & PyGetSetDef members are not marked up Some C struct members are not marked up in docs Dec 6, 2022
@encukou
Copy link
Member Author

encukou commented Dec 6, 2022

PyMethodDef could use the same treatment.

@encukou encukou reopened this Dec 6, 2022
encukou added a commit to encukou/cpython that referenced this issue Dec 6, 2022
These were only marked up in 3.12 (pythongh-97909), so they don't need
backcompat backflips.
@ramvikrams
Copy link
Contributor

i'll do that

miss-islington pushed a commit to miss-islington/cpython that referenced this issue Dec 17, 2022
(cherry picked from commit 8edcb30)

Co-authored-by: ram vikram singh <[email protected]>
miss-islington pushed a commit to miss-islington/cpython that referenced this issue Dec 17, 2022
(cherry picked from commit 8edcb30)

Co-authored-by: ram vikram singh <[email protected]>
miss-islington added a commit that referenced this issue Dec 17, 2022
(cherry picked from commit 8edcb30)

Co-authored-by: ram vikram singh <[email protected]>
miss-islington added a commit that referenced this issue Dec 17, 2022
(cherry picked from commit 8edcb30)

Co-authored-by: ram vikram singh <[email protected]>
shihai1991 added a commit to shihai1991/cpython that referenced this issue Dec 18, 2022
* origin/main: (1306 commits)
  Correct CVE-2020-10735 documentation (python#100306)
  pythongh-100272: Fix JSON serialization of OrderedDict (pythonGH-100273)
  pythongh-93649: Split tracemalloc tests from _testcapimodule.c (python#99551)
  Docs: Use `PY_VERSION_HEX` for version comparison (python#100179)
  pythongh-97909: Fix markup for `PyMethodDef` members (python#100089)
  pythongh-99240: Reset pointer to NULL when the pointed memory is freed in argument parsing (python#99890)
  pythongh-99240: Reset pointer to NULL when the pointed memory is freed in argument parsing (python#99890)
  pythonGH-98831: Add DECREF_INPUTS(), expanding to DECREF() each stack input (python#100205)
  pythongh-78707: deprecate passing >1 argument to `PurePath.[is_]relative_to()` (pythonGH-94469)
  pythongh-99540: Constant hash for _PyNone_Type to aid reproducibility (pythonGH-99541)
  pythongh-100039: enhance __signature__ to work with str and callables (pythonGH-100168)
  pythongh-99830: asyncio: Document returns of remove_{reader,writer} (python#100302)
  "Compound statement" docs: Fix with-statement step indexing (python#100286)
  pythonGH-90043: Handle NaNs in COMPARE_OP_FLOAT_JUMP (pythonGH-100278)
  Improve stats presentation for calls. (pythonGH-100274)
  Better stats for `LOAD_ATTR` and `STORE_ATTR` (pythonGH-100295)
  pythongh-81057: Move the Cached Parser Dummy Name to _PyRuntimeState (python#100277)
  Document that zipfile's pwd parameter is a `bytes` object (python#100209)
  pythongh-99767: mark `PyTypeObject.tp_watched` as internal use only in table (python#100271)
  Fix typo in introduction.rst (python#100266)
  ...
carljm added a commit to carljm/cpython that referenced this issue Dec 19, 2022
* main:
  pythongh-89727: Fix os.walk RecursionError on deep trees (python#99803)
  Docs: Don't upload CI artifacts (python#100330)
  pythongh-94912: Added marker for non-standard coroutine function detection (python#99247)
  Correct CVE-2020-10735 documentation (python#100306)
  pythongh-100272: Fix JSON serialization of OrderedDict (pythonGH-100273)
  pythongh-93649: Split tracemalloc tests from _testcapimodule.c (python#99551)
  Docs: Use `PY_VERSION_HEX` for version comparison (python#100179)
  pythongh-97909: Fix markup for `PyMethodDef` members (python#100089)
  pythongh-99240: Reset pointer to NULL when the pointed memory is freed in argument parsing (python#99890)
  pythongh-99240: Reset pointer to NULL when the pointed memory is freed in argument parsing (python#99890)
  pythonGH-98831: Add DECREF_INPUTS(), expanding to DECREF() each stack input (python#100205)
  pythongh-78707: deprecate passing >1 argument to `PurePath.[is_]relative_to()` (pythonGH-94469)
@hugovk
Copy link
Member

hugovk commented Jul 31, 2024

Triage: can this be closed?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir
Projects
None yet
Development

No branches or pull requests

4 participants