diff --git a/docs/source/index.rst b/docs/source/index.rst index 2a2b2022..b66bb27e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -39,6 +39,7 @@ The Xeus-Cpp is a Jupyter kernel for the C++ programming language UsingXeus-Cpp tutorials magics + inline_help dev-build-options debug FAQ diff --git a/docs/source/inline_help.rst b/docs/source/inline_help.rst new file mode 100644 index 00000000..8db8541f --- /dev/null +++ b/docs/source/inline_help.rst @@ -0,0 +1,65 @@ +Inline documentation +-------------------- + +The standard library +==================== + +The ``xeus-cpp`` 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. + +.. image:: vector_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-cpp`` "data" +directory of the installation prefix, namely + +.. code:: + + PREFIX/share/xeus-cpp/tagfiles + +For ``xeus-cpp`` to be able to make use of that information, a JSON +configuration file must be placed under the ``xeus-cpp`` `configuration` +directory of the installation prefix, namely + +.. code:: + + PREFIX/etc/xeus-cpp/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 + +.. code:: json + + { + "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 + +.. code:: json + + { + "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. + +.. _cppreference: https://en.cppreference.com +.. _`relevant section`: https://www.doxygen.nl/manual/external.html diff --git a/docs/source/vector_help.png b/docs/source/vector_help.png new file mode 100644 index 00000000..ad3e3324 Binary files /dev/null and b/docs/source/vector_help.png differ