gh-132661: Document t-strings and templatelib

[davepeck]

[DRAFT] This has only just begun and is very much a work in progress; putting up a draft PR now for visibility.

We're keeping a TODO list of PEP 750 documentation tasks. There's lots to do.

• Issue: Implement PEP 750 – Template Strings #132661

---

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

[hugovk]

Lint fix, either use double backticks (this is RST not MD):

Suggested change

	- Rather than evaluating to a `str` object, t-strings evaluate to a
	- Rather than evaluating to a ``str`` object, t-strings evaluate to a

Or create link:

Suggested change

	- Rather than evaluating to a `str` object, t-strings evaluate to a
	- Rather than evaluating to a :class:`str` object, t-strings evaluate to a

[hugovk]

Suggested change

	the expressions are evaluated and a new `Interpolation` object (also from the
	:mod:`string.templatelib` module) is created, which contains the evaluated
	value of the expression. That `Interpolation` object is found in the containing
	`Template`.
	the expressions are evaluated and a new :class:`~string.templatelib.Interpolation` object (also from the
	:mod:`string.templatelib` module) is created, which contains the evaluated
	value of the expression. That :class:`~string.templatelib.Interpolation` object is found in the containing
	:class:`~string.templatelib.Template`.

[hugovk]

Suggested change

	`Template` object from the :mod:`string.templatelib` module.
	:class:`~string.templatelib.Template` object from the :mod:`string.templatelib` module.

[hugovk]

We try to avoid creating too many hyperlinks, see:
https://devguide.python.org/documentation/style-guide/#links

So we don't need to link this one back to this same section. We can prevent Sphinx from linking like this, but it still applies the other formatting:

Suggested change

	The :class:`Template` class describes the contents of a template string.
	The :class:`!Template` class describes the contents of a template string.

[hugovk]

We try to avoid creating too many hyperlinks, see:
https://devguide.python.org/documentation/style-guide/#links

So we don't need to link this repeated mentions. We can prevent Sphinx from linking like this, but it still applies the other formatting:

Suggested change

	The most common way to create a new :class:`Template` instance is to use the t-string literal syntax. This syntax is identical to that of :ref:`f-strings`, except that the string is prefixed with a ``t`` instead of an ``f``. For example, the following code creates a :class:`Template` that can be used to format strings:
	The most common way to create a new :class:`!Template` instance is to use the t-string literal syntax. This syntax is identical to that of :ref:`f-strings`, except that the string is prefixed with a ``t`` instead of an ``f``. For example, the following code creates a :class:`!Template` that can be used to format strings:

Also, please try and wrap at ~80 chars.

https://devguide.python.org/documentation/markup/#use-of-whitespace

[hugovk]

Suggested change

	It is also possible to create a :class:`Template` directly, using its constructor. This takes an arbitrary collection of strings and :class:`Interpolation` instances:
	It is also possible to create a :class:`!Template` directly, using its constructor. This takes an arbitrary collection of strings and :class:`Interpolation` instances:

[hugovk]

Similarly, we try and avoid linking back to the same unit.

Suggested change

	Create a new :class:`Template` object.
	:param args: A mix of strings and :class:`Interpolation` instances in any order.
	:type args: str | Interpolation
	If two or more consecutive strings are passed, they will be concatenated into a single value in the :attr:`~Template.strings` attribute. For example, the following code creates a :class:`Template` with a single final string:
	Create a new :class:`!Template` object.
	:param args: A mix of strings and :class:`Interpolation` instances in any order.
	:type args: str | Interpolation
	If two or more consecutive strings are passed, they will be concatenated into a single value in the :attr:`~Template.strings` attribute. For example, the following code creates a :class:`!Template` with a single final string:

[hugovk]

Suggested change

	Create a new :class:`Interpolation` object.
	Create a new :class:`!Interpolation` object.

[hugovk]

Suggested change

	The :class:`Interpolation` type represents an expression inside a template string. It is shallow immutable -- its attributes cannot be reassigned.
	The :class:`!Interpolation` type represents an expression inside a template string. It is shallow immutable -- its attributes cannot be reassigned.

[davepeck]

@hugovk Thank you for the review and the helpful early feedback! Useful to know about linking.

(FWIW this is very early stage still, so I expect plenty more linting and other issues that we'll eventually resolve.)