Embedding Single Items

For the examples below, assume the existence of a Python module called elements with the following contents:

# elements.py

CARBON_WEIGHT = 12.011
SILICON_SYMBOL = 'Si'

Role: str – embed the string conversion of an object

Single values from Python code may be included in this documentation using the :str: role, like this:

The atomic weight of carbon-12 is :str:`elements.CARBON_WEIGHT`.

which gives:

The atomic weight of carbon-12 is 12.011.

The value here is a float, but any Python object which can be converted to a string using the built string constructor str(obj) is suitable, which will ultimately invoke the __str__() special method of the object being formatted.

Role: repr – embed the string representation of an object

By using the :repr: role instead, the alternative Python string representation (usually intended for consumption by developers) can be inserted:

By passing the string key, such as :repr:`elements.SILICON_SYMBOL`, to the function the
corresponding element name can be retrieved.

which gives:

By passing the string key, such as ‘Si’, to the function the corresponding element name can be retrieved.

Note that the quotes now included in the string, as they are part of the representation of the object returned by the built-in repr(obj) function, which will ultimately invoke the __repr__() special method of the object being embedded.

Role: format – embed a formatted string representation of an object

By using the :format: role, you can gain control over the formatting of Python objects.

The value of the mathematic constant *e* is :format:`math.e, .3f` to three decimal places.

which gives:

The value of the mathematic constant e is 2.718 to three decimal places.

The role accepts two items separated by a comma. The first is a reference to the object to be embedded. The second is a format specifier. The object being embedded here is a float, but any Python object which can be passed to the built-in format() function can be used. The allowable values for the format specifier depend on the type of the object being formatted.

Role: literal-repr – embed the string representation of an object as a literal

By using the :literal-repr: role the alternative Python string representation (usually intended for consumption by developers) can be inserted:

By passing the string key, such as :literal-repr:`elements.SILICON_SYMBOL`, to the function the
corresponding element name can be retrieved.

which gives:

By passing the string key, such as 'Si', to the function the corresponding element name can be retrieved.

Note that the quotes now included in the string, as they are part of the representation of the object returned by the built-in repr(obj) function, which will ultimately invoke the __repr__() special method of the object being embedded.

Role: literal-str – embed the string conversion of an object as a literal

Single values from Python code may be included in this documentation as literals using the :literal-str: role, like this:

The atomic weight of carbon-12 is :literal-str:`elements.CARBON_WEIGHT`.

which gives:

The atomic weight of carbon-12 is 12.011.

The value here is a float, but any Python object which can be converted to a string using the built string constructor str(obj) is suitable, which will ultimately invoke the __str__() special method of the object being formatted.

Role: literal-format – embed a formatted string representation of an object

By using the :literal-format: role, you can gain control over the formatting of Python objects included in the document as literals.

The value of the mathematic constant *e* is :literal-format:`math.e, .3f` to three decimal places.

which gives:

The value of the mathematic constant e is 2.718 to three decimal places.

The role accepts two items separated by a comma. The first is a reference to the object to be embedded. The second is a format specifier. The object being embedded here is a float, but any Python object which can be passed to the built-in format() function can be used. The allowable values for the format specifier depend on the type of the object being formatted.