Document attr and attribute #1311
Conversation
|
All commit authors signed the Contributor License Agreement. |
|
First, of all, please could you sign the CLA? |
|
Can you mention the Issue number on the PR description (instead of in the title?) E.g. |
kokoavailable
changed the title
Done! Thank you. |
Done!! |
There was a problem hiding this comment.
Thanks!
Let's compare "functions definitions" and "functions references" in the quick reference table:
Let's add "attribute definitions" and "attribute references" to the table. The attribute definition are already in the "Information units" section, and let's add the references to the "Roles" section.
[fix] commit suggestion Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
[fix] delete dup Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
|
@python/organization-owners Please could you enable https://pre-commit.ci for this repo? |
done! |
documentation/markup.rst
Outdated
| @@ -24,6 +24,8 @@ variables/literals/code ````foo````, ````42````, ````len(s) - 1```` :ref:`inline | |||
| True/False/None ````True````, ````False````, ````None```` :ref:`inline-markup` | |||
| functions definitions ``.. function:: print(*args)`` :ref:`directives` | |||
| functions references ``:func:`print``` :ref:`roles` | |||
| attribute definitions ``.. attribute: `attr-name``` :ref:`directives` | |||
There was a problem hiding this comment.
| attribute definitions ``.. attribute: `attr-name``` :ref:`directives` | |
| attribute definitions ``.. attribute: `attr-name``` :ref:`information-units` |
There was a problem hiding this comment.
I'm not sure this should be added. In the table I used .. function:/:func: as an example, but the same applies for classes, methods, attributes and several other directives/roles pairs.
Perhaps a separate table associating directives with the roles that can be used to link to them would be better? (If this is done, it should be a separate PR.).
documentation/markup.rst
Outdated
|
|
||
| Refer to an attribute, use the ``:attr:`` role:: |
There was a problem hiding this comment.
| Refer to an attribute, use the ``:attr:`` role:: | |
| Refer to an attribute using the ``:attr:`` role:: |
There was a problem hiding this comment.
While this is useful here, the same could be done for other directives too, like the class just above or the method just below. It would be nice if the documentation was consistent.
There was a problem hiding this comment.
While this is useful here, the same could be done for other directives too, like the
classjust above or themethodjust below. It would be nice if the documentation was consistent.
should it be seperate pr?
There was a problem hiding this comment.
Either way is fine, but smaller PRs are easier to review and merge.
Would you like to make a separate follow-up PR? :)
There was a problem hiding this comment.
Either way is fine, but smaller PRs are easier to review and merge.
Would you like to make a separate follow-up PR? :)
sure. and when will this pr be merged ? #1311
There was a problem hiding this comment.
Let's do it now :)
Thank you for the PR!
information-units Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
, using Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Document attr and attribute. Closes #1308
📚 Documentation preview 📚: https://cpython-devguide--1311.org.readthedocs.build/documentation/markup/