sample API documentation and generated content

Python API

test_py_module

autodoc example
.. automodule:: test_py_module.test
   :members:
   :private-members:
   :special-members:

Test Module for sphinx_rtd_theme.

class test_py_module.test.Foo[source]

Docstring for class Foo.

This text tests for the formatting of docstrings generated from output sphinx.ext.autodoc. Which contain reST, but sphinx nests it in the <dl>, and <dt> tags. Also, <tt> is used for class, method names and etc, but those will always have the .descname or .descclassname class.

Normal <tt> (like the <tt> I just wrote here) needs to be shown with the same style as anything else with ``this type of markup``.

It’s common for programmers to give a code example inside of their docstring:

from test_py_module import Foo

myclass = Foo()
myclass.dothismethod('with this argument')
myclass.flush()

print(myclass)

Here is a link to capitalize(). Here is a link to __init__().

__init__(qux, spam=False)[source]

Start the Foo.

Parameters:
qux : str

The first argument to initialize class.

spam : bool

Spam me yes or no…

__weakref__

list of weak references to the object

add(val1, val2)[source]

Return the added values.

Parameters:
val1 : int

First number to add.

val2 : int

Second number to add.

Return type:

int

another_function(a, b, **kwargs)[source]

Here is another function.

Parameters:
a : int

The number of green hats you own.

b : int

The number of non-green hats you own.

kwargs : float

Additional keyword arguments. Each keyword parameter should specify the name of your favorite cuisine. The values should be floats, specifying the mean price of your favorite dish in that cooking style.

Returns:

A 2-tuple. The first element is the mean price of all dishes across cuisines. The second element is the total number of hats you own: \(a + b\).

Return type:

tuple

Raises:

ValueError – When a is not an integer.

Added in version 1.0: This was added in 1.0

Changed in version 2.0: This was changed in 2.0

Deprecated since version 3.0: This is deprecated since 3.0

bar = 1

Doc comment for class attribute Foo.bar. It can have multiple lines.

baz = 2

Docstring for class attribute Foo.baz.

capitalize(myvalue)[source]

Return a string as uppercase.

Parameters:
myvalue : str

String to change

Return type:

str

flox = 1.5

Doc comment for Foo.flox. One line only.

qux

Doc comment for instance attribute qux.

property qux_caps: str

Return the instance qux as uppercase.

property qux_caps_cached: str

Return the cached value of instance qux as uppercase.

spam

Docstring for instance attribute spam.

test_py_module.test.func(
    long: int,
    param: str,
    args: None,
    flags: bool,
    lists: list | tuple)[source]

A function with many parameters.

Python function with multiple signatures
.. py:function:: overloaded_func(a: int, b: int) -> int
                 overloaded_func(a: float, b: float) -> float

   Adds :py:param:`a` and :py:param:`b`.

   :param a: First operand.
   :param b: Second operand.
test_py_module.test.overloaded_func(a: int, b: int) -> int
test_py_module.test.overloaded_func(a: float, b: float) -> float

Adds a and b.

Parameters:
a: int
a: float

First operand.

b: int
b: float

Second operand.

C++ API

.. cpp:type:: MyType

   Some type
type MyType;

Some type

.. c:macro:: DEFAULT_LENGTH

.. cpp:function:: template <typename T, int K> \
                  const MyType Foo(\
                      const MyType bar, uint8_t* arr, \
                      unsigned int len = DEFAULT_LENGTH, \
                      bool baz= false)
                  const MyType Foo(\
                      const MyType bar, uint16_t* arr, \
                      unsigned int len = DEFAULT_LENGTH, \
                      bool baz= false)

   Some function type thing

   :tparam T: Some type template parameter.
   :tparam K: Some non-type template parameter.
   :param bar: This is the bar parameter.
   :param arr[out]: Array of something.  Elements may be either
       :cpp:expr:`uint8_t` or :cpp:expr:`uint16_t`.
   :param len: Length of :cpp:expr:`arr`.
   :param baz: Baz parameter.
DEFAULT_LENGTH
template <typename T, int K>
const MyType Foo(const MyType bar, uint8_t *arr,
                 unsigned int len = DEFAULT_LENGTH,
                 bool baz = false);
const MyType Foo(const MyType bar, uint16_t *arr,
                 unsigned int len = DEFAULT_LENGTH,
                 bool baz = false);

Some function type thing

Template Parameters:
typename T

Some type template parameter.

int K

Some non-type template parameter.

Parameters:
const MyType bar

This is the bar parameter.

out
uint8_t *arr
uint16_t *arr

Array of something. Elements may be either uint8_t or uint16_t.

unsigned int len = DEFAULT_LENGTH

Length of arr.

bool baz = false

Baz parameter.

Cross-linking of macro parameters.
.. c:macro:: MY_MACRO(X, Y, Z)

   Expands to something.

   :param X: The X parameter to the macro.
   :param Y: The Y parameter to the macro.
MY_MACRO(X, Y, Z)

Expands to something.

Parameters:
X

The X parameter to the macro.

Y

The Y parameter to the macro.

.. cpp:class:: template<typename T, typename A, typename B, typename C, std::size_t N> std::array

   Some cpp class
template <typename T, typename A, typename B, typename C,
          std::size_t N>
class std::array;

Some cpp class

.. cpp:member:: float Sphinx::version

   The description of `Sphinx::version`.
float Sphinx::version;

The description of Sphinx::version.

.. cpp:var:: int version

   The description of version.
int version;

The description of version.

.. cpp:type:: std::vector<int> List

   The description of List type.
typedef std::vector<int> List;

The description of List type.

.. cpp:enum:: MyEnum

   An unscoped enum.

   .. cpp:enumerator:: A

.. cpp:enum-class:: MyScopedEnum

   A scoped enum.

   .. cpp:enumerator:: B

      Description of enumerator B.

.. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type_t<MyScopedEnum>

   A scoped enum with non-default visibility, and with a specified underlying type.

   .. cpp:enumerator:: B
enum MyEnum;

An unscoped enum.

enumerator A;
enum class MyScopedEnum;

A scoped enum.

enumerator B;

Description of enumerator B.

protected
enum struct MyScopedVisibilityEnum : std::underlying_type_t<
    MyScopedEnum>;

A scoped enum with non-default visibility, and with a specified underlying type.

enumerator B;
C++ synopses
.. cpp:type:: synopses_ex::SomeType

   Description will be shown as a tooltip when hovering over
   cross-references to :cpp:expr:`SomeType` in other signatures as well as
   in the TOC.

   Additional description not shown in tooltip.  This is the return type
   for :cpp:expr:`Foo`.

.. cpp:function:: template <typename T, int N> \
                  synopses_ex::SomeType synopses_ex::Foo(\
                    T param, \
                    const int (&arr)[N]\
                  );

   Synopsis for this function, shown when hovering over cross references
   as well as in the TOC.

   :tparam T: Tooltip shown when hovering over cross-references to this
       template parameter.  Additional description not included in
       tooltip.
   :tparam N: Tooltip shown for N.
   :param param: Tooltip shown for cross-references to this function
       parameter param.
   :param arr: Tooltip shown for cross-references to this function
       parameter arr.  To cross reference another parameter, use the
       :rst:role:`cpp:expr` role, e.g.: :cpp:expr:`N`.  Parameters can
       also be referenced via their fake qualified name,
       e.g. :cpp:expr:`synopses_ex::Foo::N`.
   :returns: Something or other.
type synopses_ex::SomeType;

Description will be shown as a tooltip when hovering over cross-references to SomeType in other signatures as well as in the TOC.

Additional description not shown in tooltip. This is the return type for Foo.

template <typename T, int N>
synopses_ex::SomeType synopses_ex::Foo(T param,
                                       const int (&arr)[N]);

Synopsis for this function, shown when hovering over cross references as well as in the TOC.

Template Parameters:
typename T

Tooltip shown when hovering over cross-references to this template parameter. Additional description not included in tooltip.

int N

Tooltip shown for N.

Parameters:
T param

Tooltip shown for cross-references to this function parameter param.

const int (&arr)[N]

Tooltip shown for cross-references to this function parameter arr. To cross reference another parameter, use the cpp:expr role, e.g.: N. Parameters can also be referenced via their fake qualified name, e.g. synopses_ex::Foo::N.

Returns:

Something or other.

C++ function with parameter descriptions nested within class.
.. cpp:class:: synopses_ex::Class

    .. cpp:function:: Class(uint16_t _cepin, uint16_t _cspin, uint32_t _spi_speed=RF24_SPI_SPEED)

        :param _cepin: The pin attached to Chip Enable on the RF module
        :param _cspin: The pin attached to Chip Select (often labeled CSN) on the radio module.
        :param _spi_speed: The SPI speed in Hz ie: 1000000 == 1Mhz
class synopses_ex::Class;
Class(uint16_t _cepin, uint16_t _cspin,
      uint32_t _spi_speed = RF24_SPI_SPEED);
Parameters:
uint16_t _cepin

The pin attached to Chip Enable on the RF module

uint16_t _cspin

The pin attached to Chip Select (often labeled CSN) on the radio module.

uint32_t _spi_speed = RF24_SPI_SPEED

The SPI speed in Hz ie: 1000000 == 1Mhz

JavaScript API

* Link to :js:class:`ModTopLevel`

.. js:class:: ModTopLevel

   * Link to :js:meth:`mod_child_1`
   * Link to :js:meth:`ModTopLevel.mod_child_1`
class module_a.submodule.ModTopLevel()
.. js:method:: ModTopLevel.mod_child_1

   * Link to :js:meth:`mod_child_2`

.. js:method:: ModTopLevel.mod_child_2

   * Link to :js:meth:`module_a.submodule.ModTopLevel.mod_child_1`
ModTopLevel.mod_child_1()
ModTopLevel.mod_child_2()
* Link to :js:class:`ModTopLevel`

.. js:class:: ModNested

   .. js:method:: nested_child_1

      * Link to :js:meth:`nested_child_2`

   .. js:method:: nested_child_2

      * Link to :js:meth:`nested_child_1`

   .. js:method:: getJSON(href, callback, priority[, err_back, flags])

      :param string href: An URI to the location of the resource.
      :param callback: Gets called with the object.
      :param err_back:
         Gets called in case the request fails. And a lot of other
         text so we need multiple lines.
      :throws SomeError: For whatever reason in that case.
      :returns: Something.
class module_b.submodule.ModNested()
ModNested.nested_child_1()
ModNested.nested_child_2()
ModNested.getJSON(href, callback, priority[, err_back, flags])
Arguments:

  • href (string()) – An URI to the location of the resource.

  • callback – Gets called with the object.

  • err_back – Gets called in case the request fails. And a lot of other text so we need multiple lines.

Throws:

SomeError() – For whatever reason in that case.

Returns:

Something.

Generated Index

A generated index (:ref:`genindex`) is part of the Sphinx build process, unless
`html_use_index` is set to :python:`False`.

Sphinx also allows indexing by domain (programming language), as seen in the
:ref:`modindex` for the demo Python module that is documented on this page.

A generated index (Index) is part of the Sphinx build process, unless html_use_index is set to False.

Sphinx also allows indexing by domain (programming language), as seen in the Module Index for the demo Python module that is documented on this page.

Note

This theme does not support a separate search page, since the search functionality is accessible in the site’s navigation bar.

Data

.. data:: Data_item_1
          Data_item_2
          Data_item_3

   Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce congue elit eu hendrerit mattis.

Some data link :data:`Data_item_1`.
test_py_module.test.Data_item_1
test_py_module.test.Data_item_2
test_py_module.test.Data_item_3

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce congue elit eu hendrerit mattis.

Some data link Data_item_1.

Last update: Dec 16, 2024