Inline documentation

The standard library

The xeus-cling kernel allows users to access help on functions and classes of the standard library.

In a code cell, typing ?std::vector will simply display the help page on vector from the cppreference website.

_images/help.png

Enabling the quick-help feature for third-party libraries

The quick help feature can be enabled for other libraries. To do so, a doxygen tag file for your library must be placed under the xeus-cling “data” directory of the installation prefix, namely

PREFIX/share/xeus-cling/tagfiles

For xeus-cling to be able to make use of that information, a JSON configuration file must be placed under the xeus-cling configuration directory of the installation prefix, namely

PREFIX/etc/xeus-cling/tags.d

Note

For more information on how to generate tag files for a doxygen documentation, check the relevant section of the doxygen documentation.

The format for the JSON configuration file is the following

{
    "url": "Base URL for the documentation",
    "tagfile": "Name of the doxygen tagfile"
}

For example the JSON configuration file for the documentation of the standard library is

{
    "url": "https://en.cppreference.com/w/",
    "tagfile": "cppreference-doxygen-web.tag.xml"
}

Note

We recommend that you only use the https protocol for the URL. Indeed, when the notebook is served over https, content from unsecure sources will not be rendered.

The case of breathe and sphinx documentation

Another popular documentation system is the combination of doxygen and sphinx, thanks for the breathe package, which generates sphinx documentation using the XML output of doxygen.

The xhale Python package can be used to convert the sphinx inventory files produced breathe into doxygen tag files.

_images/xtensor.png