Documentation example

This document demonstrates the out-of-code documentation, which is perfect for the example-first documentation style.

Some important topic

When needed, different parts of the API can be pulled in as references:

int function(int x, int y, double z)

Some function.

This is longer documentation for this function.

Parameters

• x – Argument x

• y – Argument y

• z – Argument z

Returns

This function returns something.

We can also pull in parts of the code as examples:

    // This is a simple example:
    MyType a, b;
    a.foo();
    b.foo();

Working with multi-file

A slightly confusing aspect of Sphinx is that for multi-file documentation to link to each section correctly, each file needs to be listed in the root table of contents.

This can be customized, which is a necessity for dynamic blog-style content, but it requires adjusting the sidebar code.

A typical place to put this root table of content is at the end of the index file, and it can also be hidden.

• Documentation example
• Library API
  • Class Hierarchy
  • File Hierarchy
  • Full API
• Something else

The above was generated using the following snippet. The self refers to this document, api/library_root refers to the autogenerated root file for API documentation from exhale as configured in conf.py. The other is simply the filename of another file, which is part of the documentation.

.. toctree::
   :maxdepth: 2

   self
   api/library_root
   other