Writing Box documentation

  • NB: Last update for OpenViBE 0.16.0.

Introduction

Any box that gets added to the platform must come with its associated documentation. In order to make things more readable, a documentation template was defined which all box documentation files should follow. Writing box documentation thus consists in following this template and customizing it with box specific information such as its name, role, behaviour and so on.

Beside being a very repetitive task, writing documentation can become extremely time-consuming when it comes to maintaining it as the number of boxes keeps growing. To make things easier and faster, we propose to generate some parts of the documentation, leaving it up to developers to write those parts of the documentation that are box-specific. Writing documentation this way guarantees that all pages will all have the same aspect and structure, making it easier to navigate through them.

The plugin inspector application is responsible for the generation of several documentation elements for each box algorithm.

  • An up-to-date snapshot of each box, as it would appear in the Designer
  • A template documentation for each box, as “skeleton” file

This skeleton contains several tags which act as placeholders, indicating where human-written documentation should be inserted. Of course, skeleton files should never be modified by hand, but instead they may be regenerated by the plugin inspector if needed. As for human written documentation, it should be written in external files and use the same tags as the skeleton file to identify its different sections.

By following this procedure, it is possible for CMake to produce a complete documentation source file from the skeleton file and the human-written file. Pieces of human-written documentation can be inserted at the correct location in the skeleton file, based on tags found in both files. Doxygen then parses this source to produce the final HTML page.

 


Production pipeline of box algorithm user documentation

Human-written documentation files should have the extension .dox-part to be considered as candidates by CMake for filling skeleton files. Skeleton files should have the extension .dox-skeleton .

As stated before, human-written documentation should make use of tags for CMake to know where to insert individual pieces of documentation in the skeleton. These tags look like the following : |OVP_DocBegin_NameOfYourBox_NameOfThePart| and |OVP_DocEnd_NameOfYourBox_NameOfThePart| .

Possible documentation part names include:

  • Description A global, detailed description of the box algorithm.
  • Inputs A global introduction to box inputs.
  • Input1 - Inputn : Description of each input of the box algorithm.
  • Outputs A global introduction to box outputs.
  • Output1 - Outputn : Description of each output.
  • Settings A global introduction to box settings.
  • Setting1 - Settingn : Description of each setting.
  • Examples In this section some typical uses of the box may be mentioned, and/or some sample scenarios/tutorials making use of this box may be detailed.
  • Miscellaneous Any additional information about this box may be mentioned here, including known bugs, performance issues, related boxes, etc.

The procedure

Here is the step-by-step procedure to generate the documentation.

  • Doxygen is not a part of the OpenViBE dependencies, you have to manually install it. You can download Doxygen here .
  • Make sure the component to be documented is included by the recursive traversal initiated by the main CMakeLists.txt of OpenViBE. The requirement is that the cmake script OvAddProjects.cmake gets called for the directory your component is in, and that the directory follows the usual OpenViBE conventions. If you have added your component as the other OpenVibe components, this should be the case automatically.
  • Enable building of documentation in the main CMakeLists.txt by commenting out SET(SKIP_DOCUMENTATION "1") with #.
  • Build OpenViBE using the provided build script. (Visual Studio IDE build may not work for this part).
  • All dox-part-skeleton and dox-skeleton files are generated under local-tmp/documentation/src/box-algorithm-doc and local-tmp/documentation/src/algorithm-doc.
  • Complete the file Doc_BoxAlgorithm_YourBoxName.dox-part-skeleton with your documentation, and rename the file with the extension dox-part.
  • Move the dox-part file into the doc/ directory of the module.
  • Build OpenViBE once again. The HTML documentation is generated in dist/doc/openvibe/html.
  • Opening index.html with your web browser will show you how the documentation section would look like.
  • Enjoy a cup of coffee.

Example

As an example, we will look at the documentation of the Brainamp file reader.

The .dox-skeleton file

The .dox-sekeleton file generated by the plugin-inspector for this box algorithm looks like this :

 (click here to show content)
 (click here to hide content)

File: Doc_BoxAlgorithm_BrainampFileReader.dox-skeleton in local-tmp/YourPlatformName/documentation/src/box-algorithm-doc
/**
 * \page Doc_BoxAlgorithm_BrainampFileReader Brainamp file reader
 * \section Doc_BoxAlgorithm_BrainampFileReader_Summary Summary
 * \image html Doc_BoxAlgorithm_BrainampFileReader.png
 *
 * - Plugin name : Brainamp file reader
 * - Version : 1.0
 * - Author : Yann Renard
 * - Company : INRIA/IRISA
 * - Short description :
 * - Documentation template generation date : Oct 11 2011
 *
 * \section Doc_BoxAlgorithm_BrainampFileReader_Description Description
 *
 *
 * @Doc_BoxAlgorithm_BrainampFileReader_Description_Content@
 *
 * \section Doc_BoxAlgorithm_BrainampFileReader_Outputs Outputs
 *
 * @Doc_BoxAlgorithm_BrainampFileReader_Outputs_Content@
 * \subsection Doc_BoxAlgorithm_BrainampFileReader_Output_1 1. Experiment information
 * @Doc_BoxAlgorithm_BrainampFileReader_Output1_Content@
 *
 * - Type identifier : \ref Doc_Streams_ExperimentInformation "Experiment information" <em>(0x403488e7, 0x565d70b6)</em>
 *
 * \subsection Doc_BoxAlgorithm_BrainampFileReader_Output_2 2. EEG stream
 * @Doc_BoxAlgorithm_BrainampFileReader_Output2_Content@
 *
 * - Type identifier : \ref Doc_Streams_Signal "Signal" <em>(0x5ba36127, 0x195feae1)</em>
 *
 * \subsection Doc_BoxAlgorithm_BrainampFileReader_Output_3 3. Stimulations
 * @Doc_BoxAlgorithm_BrainampFileReader_Output3_Content@
 *
 * - Type identifier : \ref Doc_Streams_Stimulations "Stimulations" <em>(0x6f752dd0, 0x082a321e)</em>
 *
 * \section Doc_BoxAlgorithm_BrainampFileReader_Settings Settings
 *
 * @Doc_BoxAlgorithm_BrainampFileReader_Settings_Content@
 * \subsection Doc_BoxAlgorithm_BrainampFileReader_Setting_1 1. Filename (header)
 * @Doc_BoxAlgorithm_BrainampFileReader_Setting1_Content@
 *
 * - Type identifier : <em> Filename (0x330306dd, 0x74a95f98)</em>
 *
 * - Default value : [ <em></em> ]
 *
 * \subsection Doc_BoxAlgorithm_BrainampFileReader_Setting_2 2. Epoch size (in sec)
 * @Doc_BoxAlgorithm_BrainampFileReader_Setting2_Content@
 *
 * - Type identifier : <em> Float (0x512a166f, 0x5c3ef83f)</em>
 *
 * - Default value : [ <em>0.0625</em> ]
 *
 *
 * \section Doc_BoxAlgorithm_BrainampFileReader_Examples Examples
 * @Doc_BoxAlgorithm_BrainampFileReader_Examples_Content@
 *
 *  \section Doc_BoxAlgorithm_BrainampFileReader_Miscellaneous Miscellaneous
 * @Doc_BoxAlgorithm_BrainampFileReader_Miscellaneous_Content@
 */

As you can see, several placeholders exist in this file. They are tagged in order to identify where hand written documentation parts should be inserted. Examples of such tags include :

  • @Doc_BoxAlgorithm_BrainampFileReader_Description_Content@
  • @Doc_BoxAlgorithm_BrainampFileReader_Output0_Content@
  • etc…

The .dox-part file

Documenting this box for its potential users and from a developer point of view consists in creating a .dox-part file with different tagged sections. Tags should follow the following structure : |OVP_DocBegin_NameOfYourBox_NameOfThePart| and |OVP_DocEnd_NameOfYourBox_NameOfThePart| tags, where NameOfThePart should be replaced with the appropriate token depending on what aspect of the box is being documented.

A typical tagged .dox-part file would look like the following :

 (click here to show content)
 (click here to hide content)

File: Doc_BoxAlgorithm_BrainampFileReader.dox-part in plugins/processing/file-io/doc
/**
 * \page BoxAlgorithm_BrainampFileReader Brainamp file reader
__________________________________________________________________

Detailed description
__________________________________________________________________

 * |OVP_DocBegin_BoxAlgorithm_BrainampFileReader_Description|
 * Loads experiment information, signal and stimulations data from Brainamp files.
 * |OVP_DocEnd_BoxAlgorithm_BrainampFileReader_Description|
__________________________________________________________________

Outputs description
__________________________________________________________________

 * |OVP_DocBegin_BoxAlgorithm_BrainampFileReader_Outputs|
 * |OVP_DocEnd_BoxAlgorithm_BrainampFileReader_Outputs|

 * |OVP_DocBegin_BoxAlgorithm_BrainampFileReader_Output1|
 * This stream contains information about the experiment and subject.
 * |OVP_DocEnd_BoxAlgorithm_BrainampFileReader_Output1|

 * |OVP_DocBegin_BoxAlgorithm_BrainampFileReader_Output2|
 * Contains the signal information for the different channels (read from the GDF file).
 * |OVP_DocEnd_BoxAlgorithm_BrainampFileReader_Output2|

 * |OVP_DocBegin_BoxAlgorithm_BrainampFileReader_Output3|
 * Contains information about the stimulations that occured during the experiment.
 * |OVP_DocEnd_BoxAlgorithm_BrainampFileReader_Output3|
__________________________________________________________________

Settings description
__________________________________________________________________

 * |OVP_DocBegin_BoxAlgorithm_BrainampFileReader_Settings|
 * |OVP_DocEnd_BoxAlgorithm_BrainampFileReader_Settings|

 * |OVP_DocBegin_BoxAlgorithm_BrainampFileReader_Setting1|
 * This setting contains the name of the brainamp header file. The other files are deduced
 * from the header content (signal content and markers).
 * |OVP_DocEnd_BoxAlgorithm_BrainampFileReader_Setting1|

 * |OVP_DocBegin_BoxAlgorithm_BrainampFileReader_Setting2|
 * This setting sets the size of epochs to be generated by this box, in seconds.
 * |OVP_DocEnd_BoxAlgorithm_BrainampFileReader_Setting2|
__________________________________________________________________

Examples description
__________________________________________________________________

 * |OVP_DocBegin_BoxAlgorithm_BrainampFileReader_Examples|
 * |OVP_DocEnd_BoxAlgorithm_BrainampFileReader_Examples|

__________________________________________________________________

Miscellaneous description
__________________________________________________________________

 * |OVP_DocBegin_BoxAlgorithm_BrainampFileReader_Miscellaneous|
 * Experiment information is stored in a header file which the user needs to specify
 * when setting up the box. When started, the box then works up the names of two additional
 * files : a data file and a marker file. Signal data is retrieved from the data file,
 * stimulations from the marker file.
 *
 * The stimulation makers are transformed in §OpenViBE§ format with the
 * \c OVTK_StimulationId_Label base. See the \ref Doc_Stimulations page
 * for more details about §OpenViBE§ stimulations.
 * |OVP_DocEnd_BoxAlgorithm_BrainampFileReader_Miscellaneous|
 */

Given this .dox-part file, CMake is able to produce the final Doxygen source file, inserting each tagged part in the .dox-skeleton file.

The final documentation source

Given the two previous files, CMake will be able to generate the final documentation source, replacing \\@ delimited tokens with their respective human-written documentation parts.

The final file would look like the following :

 (click here to show content)
 (click here to hide content)

/**
 * \page Doc_BoxAlgorithm_BrainampFileReader Brainamp file reader
 * \section Doc_BoxAlgorithm_BrainampFileReader_Summary Summary
 * \image html Doc_BoxAlgorithm_BrainampFileReader.png
 *
 * - Plugin name : Brainamp file reader
 * - Version : 1.0
 * - Author : Yann Renard
 * - Company : INRIA/IRISA
 * - Short description :
 * - Documentation template generation date : Oct 11 2011
 *
 * \section Doc_BoxAlgorithm_BrainampFileReader_Description Description
 *
 *
 *
 * Loads experiment information, signal and stimulations data from Brainamp files.
 *
 *
 * \section Doc_BoxAlgorithm_BrainampFileReader_Outputs Outputs
 *
 *
 *
 * \subsection Doc_BoxAlgorithm_BrainampFileReader_Output_1 1. Experiment information
 *
 * This stream contains information about the experiment and subject.
 *
 *
 * - Type identifier : \ref Doc_Streams_ExperimentInformation "Experiment information" <em>(0x403488e7, 0x565d70b6)</em>
 *
 * \subsection Doc_BoxAlgorithm_BrainampFileReader_Output_2 2. EEG stream
 *
 * Contains the signal information for the different channels (read from the GDF file).
 *
 *
 * - Type identifier : \ref Doc_Streams_Signal "Signal" <em>(0x5ba36127, 0x195feae1)</em>
 *
 * \subsection Doc_BoxAlgorithm_BrainampFileReader_Output_3 3. Stimulations
 *
 * Contains information about the stimulations that occured during the experiment.
 *
 *
 * - Type identifier : \ref Doc_Streams_Stimulations "Stimulations" <em>(0x6f752dd0, 0x082a321e)</em>
 *
 * \section Doc_BoxAlgorithm_BrainampFileReader_Settings Settings
 *
 *
 *
 * \subsection Doc_BoxAlgorithm_BrainampFileReader_Setting_1 1. Filename (header)
 *
 * This setting contains the name of the brainamp header file. The other files are deduced
 * from the header content (signal content and markers).
 *
 *
 * - Type identifier : <em> Filename (0x330306dd, 0x74a95f98)</em>
 *
 * - Default value : [ <em></em> ]
 *
 * \subsection Doc_BoxAlgorithm_BrainampFileReader_Setting_2 2. Epoch size (in sec)
 *
 * This setting sets the size of epochs to be generated by this box, in seconds.
 *
 *
 * - Type identifier : <em> Float (0x512a166f, 0x5c3ef83f)</em>
 *
 * - Default value : [ <em>0.0625</em> ]
 *
 *
 * \section Doc_BoxAlgorithm_BrainampFileReader_Examples Examples
 *
 *
 *
 *  \section Doc_BoxAlgorithm_BrainampFileReader_Miscellaneous Miscellaneous
 *
 * Experiment information is stored in a header file which the user needs to specify
 * when setting up the box. When started, the box then works up the names of two additional
 * files : a data file and a marker file. Signal data is retrieved from the data file,
 * stimulations from the marker file.
 *
 * The stimulation makers are transformed in §OpenViBE§ format with the
 * \c OVTK_StimulationId_Label base. See the \ref Doc_Stimulations page
 * for more details about §OpenViBE§ stimulations.
 *
 */

Notice how only text lying within a |OVP_DocBegin_NameOfYourBox_NameOfThePart| and |OVP_DocEnd_NameOfYourBox_NameOfThePart| tag pair was included in the final source file, while the rest was discarded by CMake.

The HTML page corresponding to this source can be seen on the Brainamp file reader page !

If a box you implemented is a good candidate to integration in the official release, you will be asked to provide the documentation page (i.e. the .dox-part file) so we can add it on the website.

This entry was posted in Box plugins and tagged , , . Bookmark the permalink.