Skip to content

Commit

Permalink
gh-101100: Remove roles of sample classes in howto/*
Browse files Browse the repository at this point in the history
Removed sphinx roles of some classes and methods,
as the classes are defined in the sample codes, not in Python.

Fixed warnings:
```
howto/descriptor.rst:45: WARNING: py:class reference target not found: Ten [ref.class]
howto/descriptor.rst:218: WARNING: py:class reference target not found: Person [ref.class]
howto/descriptor.rst:218: WARNING: py:class reference target not found: Person [ref.class]
howto/descriptor.rst:256: WARNING: py:class reference target not found: Person [ref.class]
howto/descriptor.rst:340: WARNING: py:class reference target not found: Validator [ref.class]
howto/descriptor.rst:363: WARNING: py:class reference target not found: Validator [ref.class]
howto/descriptor.rst:363: WARNING: py:meth reference target not found: validate [ref.meth]
howto/descriptor.rst:372: WARNING: py:class reference target not found: OneOf [ref.class]
howto/descriptor.rst:374: WARNING: py:class reference target not found: Number [ref.class]
howto/descriptor.rst:378: WARNING: py:class reference target not found: String [ref.class]
howto/descriptor.rst:876: WARNING: py:class reference target not found: Field [ref.class]
howto/descriptor.rst:1143: WARNING: py:func reference target not found: Property [ref.func]
howto/descriptor.rst:1725: WARNING: py:class reference target not found: Object [ref.class]
howto/enum.rst:78: WARNING: py:class reference target not found: Weekday [ref.class]
howto/enum.rst:90: WARNING: py:class reference target not found: Weekday [ref.class]
howto/enum.rst:113: WARNING: py:class reference target not found: Weekday [ref.class]
howto/enum.rst:131: WARNING: py:class reference target not found: Weekday [ref.class]
howto/enum.rst:576: WARNING: py:class reference target not found: Animal [ref.class]
howto/enum.rst:893: WARNING: py:class reference target not found: FloatEnum [ref.class]
```
  • Loading branch information
koyuki7w committed Nov 21, 2024
1 parent c9b399f commit 54ad726
Show file tree
Hide file tree
Showing 2 changed files with 19 additions and 19 deletions.
26 changes: 13 additions & 13 deletions Doc/howto/descriptor.rst
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ add new capabilities one by one.
Simple example: A descriptor that returns a constant
----------------------------------------------------

The :class:`Ten` class is a descriptor whose :meth:`__get__` method always
The ``Ten`` class is a descriptor whose :meth:`__get__` method always

Check warning on line 45 in Doc/howto/descriptor.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs

py:meth reference target not found: __get__ [ref.meth]
returns the constant ``10``:

.. testcode::
Expand Down Expand Up @@ -215,8 +215,8 @@ Customized names
When a class uses descriptors, it can inform each descriptor about which
variable name was used.

In this example, the :class:`Person` class has two descriptor instances,
*name* and *age*. When the :class:`Person` class is defined, it makes a
In this example, the ``Person`` class has two descriptor instances,

Check warning on line 218 in Doc/howto/descriptor.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs

py:meth reference target not found: __set_name__ [ref.meth]
*name* and *age*. When the ``Person`` class is defined, it makes a
callback to :meth:`__set_name__` in *LoggedAccess* so that the field names can
be recorded, giving each descriptor its own *public_name* and *private_name*:

Expand Down Expand Up @@ -253,7 +253,7 @@ be recorded, giving each descriptor its own *public_name* and *private_name*:
def birthday(self):
self.age += 1

An interactive session shows that the :class:`Person` class has called
An interactive session shows that the ``Person`` class has called

Check warning on line 256 in Doc/howto/descriptor.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs

py:meth reference target not found: __set_name__ [ref.meth]
:meth:`__set_name__` so that the field names would be recorded. Here
we call :func:`vars` to look up the descriptor without triggering it:

Expand Down Expand Up @@ -337,7 +337,7 @@ any data, it verifies that the new value meets various type and range
restrictions. If those restrictions aren't met, it raises an exception to
prevent data corruption at its source.

This :class:`Validator` class is both an :term:`abstract base class` and a
This ``Validator`` class is both an :term:`abstract base class` and a
managed attribute descriptor:

.. testcode::
Expand All @@ -360,22 +360,22 @@ managed attribute descriptor:
def validate(self, value):
pass

Custom validators need to inherit from :class:`Validator` and must supply a
:meth:`validate` method to test various restrictions as needed.
Custom validators need to inherit from ``Validator`` and must supply a
``validate`` method to test various restrictions as needed.


Custom validators
-----------------

Here are three practical data validation utilities:

1) :class:`OneOf` verifies that a value is one of a restricted set of options.
1) ``OneOf`` verifies that a value is one of a restricted set of options.

2) :class:`Number` verifies that a value is either an :class:`int` or
2) ``Number`` verifies that a value is either an :class:`int` or
:class:`float`. Optionally, it verifies that a value is between a given
minimum or maximum.

3) :class:`String` verifies that a value is a :class:`str`. Optionally, it
3) ``String`` verifies that a value is a :class:`str`. Optionally, it
validates a given minimum or maximum length. It can validate a
user-defined `predicate
<https://en.wikipedia.org/wiki/Predicate_(mathematical_logic)>`_ as well.
Expand Down Expand Up @@ -873,7 +873,7 @@ care of lookups or updates:
conn.execute(self.store, [value, obj.key])
conn.commit()

We can use the :class:`Field` class to define `models
We can use the ``Field`` class to define `models
<https://en.wikipedia.org/wiki/Database_model>`_ that describe the schema for
each table in a database:

Expand Down Expand Up @@ -1140,7 +1140,7 @@ to wrap access to the value attribute in a property data descriptor:
self.recalc()
return self._value

Either the built-in :func:`property` or our :func:`Property` equivalent would
Either the built-in :func:`property` or our ``Property`` equivalent would
work in this example.


Expand Down Expand Up @@ -1722,7 +1722,7 @@ Python:
)
super().__delattr__(name)

To use the simulation in a real class, just inherit from :class:`Object` and
To use the simulation in a real class, just inherit from ``Object`` and
set the :term:`metaclass` to :class:`Type`:

.. testcode::
Expand Down
12 changes: 6 additions & 6 deletions Doc/howto/enum.rst
Original file line number Diff line number Diff line change
Expand Up @@ -79,15 +79,15 @@ Unlike many languages that treat enumerations solely as name/value pairs,
Python Enums can have behavior added. For example, :class:`datetime.date`
has two methods for returning the weekday: :meth:`weekday` and :meth:`isoweekday`.
The difference is that one of them counts from 0-6 and the other from 1-7.
Rather than keep track of that ourselves we can add a method to the :class:`Weekday`
Rather than keep track of that ourselves we can add a method to the ``Weekday``
enum to extract the day from the :class:`date` instance and return the matching
enum member::

@classmethod
def from_date(cls, date):
return cls(date.isoweekday())

The complete :class:`Weekday` enum now looks like this::
The complete ``Weekday`` enum now looks like this::

>>> class Weekday(Enum):
... MONDAY = 1
Expand All @@ -110,7 +110,7 @@ Now we can find out what today is! Observe::

Of course, if you're reading this on some other day, you'll see that day instead.

This :class:`Weekday` enum is great if our variable only needs one day, but
This ``Weekday`` enum is great if our variable only needs one day, but
what if we need several? Maybe we're writing a function to plot chores during
a week, and don't want to use a :class:`list` -- we could use a different type
of :class:`Enum`::
Expand All @@ -128,7 +128,7 @@ of :class:`Enum`::
We've changed two things: we're inherited from :class:`Flag`, and the values are
all powers of 2.

Just like the original :class:`Weekday` enum above, we can have a single selection::
Just like the original ``Weekday`` enum above, we can have a single selection::

>>> first_week_day = Weekday.MONDAY
>>> first_week_day
Expand Down Expand Up @@ -580,7 +580,7 @@ values. The last two options enable assigning arbitrary values to
enumerations; the others auto-assign increasing integers starting with 1 (use
the ``start`` parameter to specify a different starting value). A
new class derived from :class:`Enum` is returned. In other words, the above
assignment to :class:`Animal` is equivalent to::
assignment to ``Animal`` is equivalent to::

>>> class Animal(Enum):
... ANT = 1
Expand Down Expand Up @@ -891,7 +891,7 @@ simple to implement independently::
pass

This demonstrates how similar derived enumerations can be defined; for example
a :class:`FloatEnum` that mixes in :class:`float` instead of :class:`int`.
a ``FloatEnum`` that mixes in :class:`float` instead of :class:`int`.

Some rules:

Expand Down

0 comments on commit 54ad726

Please sign in to comment.