14. Example API documentation
This section shows you how to use ReStructuredText to create an API references for C++ and Python. See Section 10, Documenting APIs for background information and examples of how to reference the components in the API.
14.1. C++ APIs
Example partly adapted from the breathe documentation.
-
int example(int a, int b)
An overly extended example of how to use breathe.
Modifed from: https://breathe.readthedocs.io/en/latest/#in-a-nutshell This is a brief summary of the example function.
This is a more complete description of the function. You can also document the parameters and return value.
You can include Markdown formatting. For example bold, bold,
codeand links: Graphcore documentation.Class names, such as Nutshell, will automatically generate a link to the documentation for the class. Function names will automatically generate links if they have brackets, for example: Nutshell::crack(). See the Doxygen documentation for more information.
To link to a specific overloaded function, you can specify the complete signature. However, this has to be on one line, so you may need to turn off linting, as shown below (note that this won’t actually generate a link, because it doesn’t know where to find the function definition):
See also
popnn::rnn::backwardGradientStep(poplar::Graph&, const poplar::Tensor&, const poplar::Tensor&, const poplar::Tensor&, const poplar::Tensor&, const poplar::Tensor &, poplar::program::Sequence&, popnn::NonLinearityType, const poplar::Type&, const poplar::DebugContext&, poplin::matmul::PlanningCache*)
-
class Nutshell
Description of the class.
Public Types
The following code shows examples of how to specifically include overloaded functions.
.. doxygenfunction:: popart::view::sub(const Regions &rhs, bool include_empty=false) const
.. doxygenfunction:: popart::view::sub(const Region &rhs, bool include_empty=false) const
.. doxygenfunction:: popart::view::contains(const Region &rhs) const
.. doxygenfunction:: popart::view::contains(const std::vector<int64_t> &index) const
14.2. Python APIs
See the Sphinx autodoc documentation for more information.
- example.example(a, b)
This is a brief summary of the example function.
This is a more complete description of the function. You can include (almost) any RST markup, for example:
x = popxl.variable(np.arange(16).reshape(4,4)) # [[ 0, 1, 2, 3], # [ 4, 5, 6, 7], # [ 8, 9, 10, 11], # [12, 13, 14, 15]] gather(x, [3, 1, 2]) == Tensor([x[3], x[1], x[2]]) # [[12, 13, 14, 15], # [ 4, 5, 6, 7], # [ 8, 9, 10, 11]]
See also
Example.example()You can also document the parameters and return value. There are different ways of describing parameters. We have not standardised on one (yet).
- class example.Example(initial_value)
An example class.
- Parameters
initial_value (float) –
- __init__(initial_value)
Create a new Example object with the initial value.
- Parameters
initial_value (float) – The initial value of the object.