gh-110679: Improved markup in enum.rst #110747

khlmood · 2023-10-12T01:17:37Z

After reviewing file, I noticed several instances where the documentation used italic formatting instead of the appropriate role formatting. I've made corrections to these instances to improve the markup.

Issue: Improve markup in enum.rst #110679

📚 Documentation preview 📚: https://cpython-previews--110747.org.readthedocs.build/

ghost · 2023-10-12T01:17:40Z

All commit authors signed the Contributor License Agreement.

JelleZijlstra · 2023-10-12T04:11:51Z

Doc/library/enum.rst

@@ -161,13 +161,13 @@ Data Types

 .. class:: EnumType

-   *EnumType* is the :term:`metaclass` for *enum* enumerations.  It is possible
+   :class:`EnumType` is the :term:`metaclass` for :class:`enum` enumerations.  It is possible


Linking EnumType here is ugly as the link would lead right back to the current paragraph. We probably should use code formatting, but not a link.

enum I believe refers to the module, not to a class—there is no class called enum. There too, I don't think a link is helpful.

JelleZijlstra · 2023-10-12T04:12:12Z

Doc/library/enum.rst

@@ -405,9 +405,9 @@ Data Types

 .. class:: IntEnum

-   *IntEnum* is the same as *Enum*, but its members are also integers and can be
+   :class:`IntEnum` is the same as :class:`Enum`, but its members are also integers and can be


Here (and several times below), it's again not helpful to add a link back to the current paragraph.

JelleZijlstra · 2023-10-12T04:12:31Z

Doc/library/enum.rst

-   than the highest value; for *StrEnum* it will be the lower-cased version of
+   :class:`auto` can be used in place of a value.  If used, the *Enum* machinery will
+   call an :class:`Enum`'s :meth:`~Enum._generate_next_value_` to get an appropriate value.
+   For :class:`Enum` and :class:`IntEnum`` that appropriate value will be the last value plus


Suggested change

For :class:`Enum` and :class:`IntEnum`` that appropriate value will be the last value plus

For :class:`Enum` and :class:`IntEnum` that appropriate value will be the last value plus

khlmood · 2023-10-13T19:04:11Z

Thank you @JelleZijlstra for your valuable feedback.

ethanfurman · 2023-10-25T14:36:03Z

Doc/library/enum.rst

@@ -165,7 +165,7 @@ Data Types
   to subclass *EnumType* -- see :ref:`Subclassing EnumType <enumtype-examples>`
   for details.

-   *EnumType* is responsible for setting the correct :meth:`!__repr__`,
+   :class:`EnumType` is responsible for setting the correct :meth:`!__repr__`,


Suggested change

:class:`EnumType` is responsible for setting the correct :meth:`!__repr__`,

``EnumType`` is responsible for setting the correct :meth:`!__repr__`,

ethanfurman · 2023-10-25T14:37:54Z

Doc/library/enum.rst

@@ -437,7 +437,7 @@ Data Types

 .. class:: StrEnum

-   *StrEnum* is the same as *Enum*, but its members are also strings and can be used
+   *StrEnum* is the same as :class:`Enum`, but its members are also strings and can be used


Suggested change

*StrEnum* is the same as :class:`Enum`, but its members are also strings and can be used

``StrEnum`` is the same as :class:`Enum`, but its members are also strings and can be used

ethanfurman · 2023-10-25T14:38:06Z

Doc/library/enum.rst

@@ -576,7 +576,7 @@ Data Types

 .. class:: IntFlag

-   *IntFlag* is the same as *Flag*, but its members are also integers and can be
+   *IntFlag* is the same as :class:`Flag`, but its members are also integers and can be


Suggested change

*IntFlag* is the same as :class:`Flag`, but its members are also integers and can be

``IntFlag`` is the same as :class:`Flag`, but its members are also integers and can be

ethanfurman · 2023-10-25T14:38:43Z

Doc/library/enum.rst

@@ -697,7 +697,7 @@ Data Types

 .. class:: FlagBoundary

-   *FlagBoundary* controls how out-of-range values are handled in *Flag* and its
+   *FlagBoundary* controls how out-of-range values are handled in :class:`Flag` and its


Suggested change

*FlagBoundary* controls how out-of-range values are handled in :class:`Flag` and its

``FlagBoundary`` controls how out-of-range values are handled in :class:`Flag` and its

bedevere-app · 2023-10-25T14:40:34Z

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

Made requested changes regarding markup.

ezio-melotti

I'm a bit late to the party, but the correct way to format those examples without generating a link would be :class:`!EnumType`. The output of this will consistent with the other :class: without creating an unnecessary link.

Improved markup in enum.rst

b87785c

khlmood requested a review from ethanfurman as a code owner October 12, 2023 01:17

bedevere-app bot added docs Documentation in the Doc dir skip news awaiting review labels Oct 12, 2023

bedevere-app bot mentioned this pull request Oct 12, 2023

Improve markup in enum.rst #110679

Closed

JelleZijlstra reviewed Oct 12, 2023

View reviewed changes

Improved markup in enum.rst II

b464665

khlmood added 2 commits October 25, 2023 11:19

Merge branch 'main' into pythongh-110679

abbabf8

Merge branch 'main' into pythongh-110679

065c5cc

ethanfurman requested changes Oct 25, 2023

View reviewed changes

bedevere-app bot added awaiting changes and removed awaiting review labels Oct 25, 2023

Update Doc/library/enum.rst

eda3438

Made requested changes regarding markup.

ethanfurman approved these changes Oct 25, 2023

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting changes labels Oct 25, 2023

ethanfurman merged commit 14f52e1 into python:main Oct 25, 2023

bedevere-app bot removed the awaiting merge label Oct 25, 2023

ezio-melotti reviewed Oct 28, 2023

View reviewed changes

khlmood deleted the gh-110679 branch November 2, 2023 16:41

aisk pushed a commit to aisk/cpython that referenced this pull request Feb 11, 2024

pythongh-110679: Improved markup in enum.rst (pythonGH-110747)

36997b1

Glyphack pushed a commit to Glyphack/cpython that referenced this pull request Sep 2, 2024

pythongh-110679: Improved markup in enum.rst (pythonGH-110747)

b9776d0

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

gh-110679: Improved markup in enum.rst #110747

gh-110679: Improved markup in enum.rst #110747

Uh oh!

khlmood commented Oct 12, 2023 •

edited by github-actions bot

Loading

Uh oh!

ghost commented Oct 12, 2023 •

edited by ghost

Loading

Uh oh!

JelleZijlstra Oct 12, 2023

Uh oh!

JelleZijlstra Oct 12, 2023

Uh oh!

JelleZijlstra Oct 12, 2023

Uh oh!

khlmood commented Oct 13, 2023

Uh oh!

ethanfurman Oct 25, 2023

Uh oh!

ethanfurman Oct 25, 2023

Uh oh!

ethanfurman Oct 25, 2023

Uh oh!

ethanfurman Oct 25, 2023

Uh oh!

bedevere-app bot commented Oct 25, 2023

Uh oh!

ezio-melotti left a comment

Uh oh!

Uh oh!

	For :class:`Enum` and :class:`IntEnum`` that appropriate value will be the last value plus
	For :class:`Enum` and :class:`IntEnum` that appropriate value will be the last value plus

	:class:`EnumType` is responsible for setting the correct :meth:`!__repr__`,
	``EnumType`` is responsible for setting the correct :meth:`!__repr__`,

	StrEnum is the same as :class:`Enum`, but its members are also strings and can be used
	``StrEnum`` is the same as :class:`Enum`, but its members are also strings and can be used

	IntFlag is the same as :class:`Flag`, but its members are also integers and can be
	``IntFlag`` is the same as :class:`Flag`, but its members are also integers and can be

	FlagBoundary controls how out-of-range values are handled in :class:`Flag` and its
	``FlagBoundary`` controls how out-of-range values are handled in :class:`Flag` and its

Uh oh!

gh-110679: Improved markup in enum.rst #110747

gh-110679: Improved markup in enum.rst #110747

Uh oh!

Conversation

khlmood commented Oct 12, 2023 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ghost commented Oct 12, 2023 • edited by ghost Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JelleZijlstra Oct 12, 2023

Choose a reason for hiding this comment

Uh oh!

JelleZijlstra Oct 12, 2023

Choose a reason for hiding this comment

Uh oh!

JelleZijlstra Oct 12, 2023

Choose a reason for hiding this comment

Uh oh!

khlmood commented Oct 13, 2023

Uh oh!

ethanfurman Oct 25, 2023

Choose a reason for hiding this comment

Uh oh!

ethanfurman Oct 25, 2023

Choose a reason for hiding this comment

Uh oh!

ethanfurman Oct 25, 2023

Choose a reason for hiding this comment

Uh oh!

ethanfurman Oct 25, 2023

Choose a reason for hiding this comment

Uh oh!

bedevere-app bot commented Oct 25, 2023

Uh oh!

ezio-melotti left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

khlmood commented Oct 12, 2023 •

edited by github-actions bot

Loading

ghost commented Oct 12, 2023 •

edited by ghost

Loading