flavors_rst API documentation

# flavors_rst

View Source

      1__docformat__ = "restructuredtext"
      2
      3
      4def links():
      5    """
      6    For type hints, read `PEP 484`_.
      7    See the `Python home page <http://www.python.org>`_ for info.
      8
      9    .. _PEP 484:
     10        https://www.python.org/dev/peps/pep-0484/
     11
     12    """
     13
     14
     15def refs():
     16    """Here we have refs to :py:obj:`links` and :func:`admonitions`."""
     17
     18
     19def admonitions():
     20    """
     21
     22    .. note::
     23
     24       This function is not suitable for sending spam e-mails.
     25
     26    .. warning::
     27       This function is not suitable for sending spam e-mails.
     28
     29    .. danger::
     30       This function is not suitable for sending **spam** e-mails.
     31
     32    .. warning::  Be Careful!
     33       This warning has both a title and content.
     34
     35    .. warning::  This warning has a title only.
     36
     37    .. versionadded:: 2.5
     38       The *spam* parameter.
     39
     40    .. versionchanged:: 2.5
     41       The *spam* parameter.
     42
     43    .. code-block::
     44        This is a code block.
     45
     46    .. deprecated:: 3.1
     47       Use :func:`spam` instead.
     48
     49    .. deprecated:: 3.1
     50
     51    This text is not part of the deprecation notice.
     52    """
     53
     54
     55def seealso():
     56    # this is not properly supported yet
     57    """
     58    .. seealso::
     59
     60       Module :py:mod:`zipfile`
     61          Documentation of the :py:mod:`zipfile` standard module.
     62
     63       `GNU tar manual, Basic Tar Format <http://link>`_
     64          Documentation for tar archive files, including GNU tar extensions.
     65    """
     66
     67
     68def seealso_short():
     69    # this is not properly supported yet
     70    """
     71    .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`
     72    """
     73
     74
     75def tables():
     76    """
     77    | Header 1 | *Header* 2 |
     78    | -------- | -------- |
     79    | `Cell 1` | [Cell 2](http://example.com) link |
     80    | Cell 3 | **Cell 4** |
     81    """
     82
     83
     84def footnote1():
     85    """
     86    Cite the relevant literature, e.g. [1]_.  You may also cite these
     87    references in the notes section above.
     88
     89    .. [1] O. McNoleg, "The integration of GIS, remote sensing,
     90       expert systems and adaptive co-kriging for environmental habitat
     91       modelling of the Highland Haggis using object-oriented, fuzzy-logic
     92       and neural-network techniques," Computers & Geosciences, vol. 22,
     93       pp. 585-588, 1996.
     94    """
     95
     96
     97def footnote2():
     98    """
     99    Autonumbered footnotes are
    100    possible, like using [#]_ and [#]_.
    101
    102    .. [#] This is the first one.
    103    .. [#] This is the second one.
    104
    105    They may be assigned 'autonumber
    106    labels' - for instance,
    107    [#fourth]_ and [#third]_.
    108
    109    .. [#third] a.k.a. third_
    110
    111    .. [#fourth] a.k.a. fourth_
    112    """
    113
    114
    115def footnote3():
    116    """
    117    Auto-symbol footnotes are also
    118    possible, like this: [*]_ and [*]_.
    119
    120    .. [*] This is the first one.
    121    .. [*] This is the second one.
    122    """
    123
    124
    125def footnote4():
    126    """
    127    There is no footnote for this reference [#]_.
    128    """
    129
    130
    131def include():
    132    """
    133    Included from another file:
    134
    135    .. include:: flavors_rst_include/include.rst
    136    """
    137
    138
    139def include_options():
    140    """
    141    Included from another file:
    142
    143    .. include:: flavors_rst_include/include_2.md
    144       :start-line: 2
    145       :end-line: 5
    146
    147
    148    Also included:
    149
    150    .. include:: flavors_rst_include/include_2.md
    151       :start-after: <!-- start here -->
    152       :end-before: <!-- end here -->
    153    """
    154
    155
    156def fields(foo: str = "foo", bar: bool = True) -> str:
    157    """This method has field descriptions.
    158
    159    :param foo: A string,
    160        defaults to None
    161    :type foo: string, optional
    162    :param bar: Another
    163     boolean.
    164    :return: Another string,
    165        or maybe `None`.
    166    :rtype: A string.
    167    """
    168    raise NotImplementedError
    169
    170
    171def fields_text_after_param(foo):
    172    """This method has text after the `:param` fields.
    173
    174    :param foo: Some text.
    175
    176    Here's some more text.
    177    """
    178
    179
    180def fields_invalid(foo: str = "foo") -> str:
    181    """This method has invalid `:param` definitions.
    182
    183    :param: What is this for?
    184
    185    :unknown: This is an unknown field name.
    186    """
    187    raise NotImplementedError
    188
    189
    190def fields_exception():
    191    """
    192    :raises RuntimeError: Some multi-line
    193        exception description.
    194    """

def links(): View Source

     5def links():
     6    """
     7    For type hints, read `PEP 484`_.
     8    See the `Python home page <http://www.python.org>`_ for info.
     9
    10    .. _PEP 484:
    11        https://www.python.org/dev/peps/pep-0484/
    12
    13    """

For type hints, read PEP 484. See the Python home page for info.

def refs(): View Source

    16def refs():
    17    """Here we have refs to :py:obj:`links` and :func:`admonitions`."""

Here we have refs to `links` and `admonitions()`.

def admonitions(): View Source

    20def admonitions():
    21    """
    22
    23    .. note::
    24
    25       This function is not suitable for sending spam e-mails.
    26
    27    .. warning::
    28       This function is not suitable for sending spam e-mails.
    29
    30    .. danger::
    31       This function is not suitable for sending **spam** e-mails.
    32
    33    .. warning::  Be Careful!
    34       This warning has both a title and content.
    35
    36    .. warning::  This warning has a title only.
    37
    38    .. versionadded:: 2.5
    39       The *spam* parameter.
    40
    41    .. versionchanged:: 2.5
    42       The *spam* parameter.
    43
    44    .. code-block::
    45        This is a code block.
    46
    47    .. deprecated:: 3.1
    48       Use :func:`spam` instead.
    49
    50    .. deprecated:: 3.1
    51
    52    This text is not part of the deprecation notice.
    53    """

This function is not suitable for sending spam e-mails.

This function is not suitable for sending spam e-mails.

This function is not suitable for sending spam e-mails.

###### Be Careful!

This warning has both a title and content.

###### This warning has a title only.

New in version 2.5: The spam parameter.

Changed in version 2.5: The spam parameter.

    This is a code block.

Deprecated since version 3.1: Use `spam()` instead.

Deprecated since version 3.1.

This text is not part of the deprecation notice.

def seealso(): View Source

    56def seealso():
    57    # this is not properly supported yet
    58    """
    59    .. seealso::
    60
    61       Module :py:mod:`zipfile`
    62          Documentation of the :py:mod:`zipfile` standard module.
    63
    64       `GNU tar manual, Basic Tar Format <http://link>`_
    65          Documentation for tar archive files, including GNU tar extensions.
    66    """

seealso: Module `zipfile` Documentation of the `zipfile` standard module.

GNU tar manual, Basic Tar Format Documentation for tar archive files, including GNU tar extensions.

def seealso_short(): View Source

    69def seealso_short():
    70    # this is not properly supported yet
    71    """
    72    .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`
    73    """

seealso modules `zipfile`, `tarfile`.

def tables(): View Source

    76def tables():
    77    """
    78    | Header 1 | *Header* 2 |
    79    | -------- | -------- |
    80    | `Cell 1` | [Cell 2](http://example.com) link |
    81    | Cell 3 | **Cell 4** |
    82    """

Header 1 | Header 2
--- | ---
`Cell 1` | Cell 2 link
Cell 3 | Cell 4

def footnote1(): View Source

    85def footnote1():
    86    """
    87    Cite the relevant literature, e.g. [1]_.  You may also cite these
    88    references in the notes section above.
    89
    90    .. [1] O. McNoleg, "The integration of GIS, remote sensing,
    91       expert systems and adaptive co-kriging for environmental habitat
    92       modelling of the Highland Haggis using object-oriented, fuzzy-logic
    93       and neural-network techniques," Computers & Geosciences, vol. 22,
    94       pp. 585-588, 1996.
    95    """

Cite the relevant literature, e.g. 1. You may also cite these references in the notes section above.

1. O. McNoleg, "The integration of GIS, remote sensing, expert systems and adaptive co-kriging for environmental habitat modelling of the Highland Haggis using object-oriented, fuzzy-logic and neural-network techniques," Computers & Geosciences, vol. 22, pp. 585-588, 1996. ↩

def footnote2(): View Source

     98def footnote2():
     99    """
    100    Autonumbered footnotes are
    101    possible, like using [#]_ and [#]_.
    102
    103    .. [#] This is the first one.
    104    .. [#] This is the second one.
    105
    106    They may be assigned 'autonumber
    107    labels' - for instance,
    108    [#fourth]_ and [#third]_.
    109
    110    .. [#third] a.k.a. third_
    111
    112    .. [#fourth] a.k.a. fourth_
    113    """

Autonumbered footnotes are possible, like using 1 and 2.

They may be assigned 'autonumber labels' - for instance, 3 and 4.

1. This is the first one. ↩

2. This is the second one. ↩

3. a.k.a. third_ ↩

4. a.k.a. fourth_ ↩

def footnote3(): View Source

    116def footnote3():
    117    """
    118    Auto-symbol footnotes are also
    119    possible, like this: [*]_ and [*]_.
    120
    121    .. [*] This is the first one.
    122    .. [*] This is the second one.
    123    """

Auto-symbol footnotes are also possible, like this: 1 and 2.

1. This is the first one. ↩

2. This is the second one. ↩

def footnote4(): View Source

    126def footnote4():
    127    """
    128    There is no footnote for this reference [#]_.
    129    """

There is no footnote for this reference [#]_.

def include(): View Source

    132def include():
    133    """
    134    Included from another file:
    135
    136    .. include:: flavors_rst_include/include.rst
    137    """

Included from another file:

Hello

World!

\( 42 \)

def include_options(): View Source

    140def include_options():
    141    """
    142    Included from another file:
    143
    144    .. include:: flavors_rst_include/include_2.md
    145       :start-line: 2
    146       :end-line: 5
    147
    148
    149    Also included:
    150
    151    .. include:: flavors_rst_include/include_2.md
    152       :start-after: <!-- start here -->
    153       :end-before: <!-- end here -->
    154    """

Included from another file:

This paragraph should be included. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec semper vitae elit ac condimentum. Aenean consequat, massa sed consequat imperdiet, risus sagittis libero eros.

Also included:

This paragraph should be included. Vestibulum fringilla metus nec lectus tincidunt tristique. Vivamus erat risus, commodo ut aliquet ut, imperdiet ac dui. Nulla dolor orci, mollis ac sagittis in, tristique nec ipsum. Ut sagittis nibh eu ex imperdiet, at aliquet ipsum elementum. Donec vehicula sem nec ante vulputate feugiat. Nulla facilisi. Phasellus viverra velit id faucibus commodo.

def fields(foo: str = 'foo', bar: bool = True) -> str: View Source

    157def fields(foo: str = "foo", bar: bool = True) -> str:
    158    """This method has field descriptions.
    159
    160    :param foo: A string,
    161        defaults to None
    162    :type foo: string, optional
    163    :param bar: Another
    164     boolean.
    165    :return: Another string,
    166        or maybe `None`.
    167    :rtype: A string.
    168    """
    169    raise NotImplementedError

This method has field descriptions.

###### Parameters

- foo: A string, defaults to None
- bar: Another boolean.

###### Returns

> Another string, or maybe `None`.

def fields_text_after_param(foo): View Source

    172def fields_text_after_param(foo):
    173    """This method has text after the `:param` fields.
    174
    175    :param foo: Some text.
    176
    177    Here's some more text.
    178    """

This method has text after the `:param` fields.

###### Parameters

- foo: Some text.

Here's some more text.

def fields_invalid(foo: str = 'foo') -> str: View Source

    181def fields_invalid(foo: str = "foo") -> str:
    182    """This method has invalid `:param` definitions.
    183
    184    :param: What is this for?
    185
    186    :unknown: This is an unknown field name.
    187    """
    188    raise NotImplementedError

This method has invalid `:param` definitions.

###### Parameters

- What is this for?

:unknown: This is an unknown field name.

def fields_exception(): View Source

    191def fields_exception():
    192    """
    193    :raises RuntimeError: Some multi-line
    194        exception description.
    195    """

###### Raises

- RuntimeError: Some multi-line exception description.