Documentation 📚

AqNWB uses Doxygen with Graphviz for documentation. The cmake related instructions on this page follow the Developer Presets installation instructions using the dev preset.

Building the Docs

1. Ensure that Doxygen and Graphviz are installed
2. Enable building the docs by setting the cmake variable BUILD_DOCS=ON, e.g., by calling cmake --preset=dev -DBUILD_DOCS=ON
3. Build the documentation by running: cmake --build --preset=dev --target=docs. The resulting documentation files can be found in your build directory build/dev/docs/html.

Note

To edit settings in cmake (e.g., to enable BUILD_DOCS=ON) after the initial configuration, you can also use the ccmake command line UI by navigating to your build directory (e.g., cd build/dev) and running ccmake ../../ (with the path pointing to the aqnwb root directory).

Creating New Documentation Pages

To create a new page as part of the For Users docs, simply create a new .dox file in the docs/pages/userdocs folder, e.g.:

docs/pages/userdocs/mypage.dox

/**
* \page mypage My New Page
*
*/

and add a corresponding - \subpage mypage entry to the page listing of the docs/pages/1_userdocs.dox file. Note, the subpage command uses the label of the page (here mypage) and not the name of the file.

Similarly, we can add pages to the For Developers docs by adding a new .dox file to the docs/pages/devdocs and including it as as subpage in docs/pages/2_devdocs.dox.

Creating Code Examples

Code examples are defined as part of the unit tests to ensure code examples used in the documentation are tested and work as expected.

Creating the Example Code

First we need to define our code example by creating a new cpp file in the tests/examples folder. Here we use the file test_examples.cpp shown below. The file looks like a regular unit test with the addition of Doxygen comments of the form // [example_hdf5io_code_snippet] to mark regions in the code that we want to include in the docs as code snippets.

test_example.cpp

#include <catch2/catch_test_macros.hpp>
 
#include "io/hdf5/HDF5IO.hpp"
#include "testUtils.hpp"
 
TEST_CASE("SimpleExamples", "[hdf5io]")
{
  SECTION("docsExample")
  {
    std::string path = getTestFilePath("testSimpleExample.h5");
    // [example_hdf5io_code_snippet]
    std::unique_ptr<AQNWB::IO::HDF5::HDF5IO> hdf5io =
        std::make_unique<AQNWB::IO::HDF5::HDF5IO>(path);
    // [example_hdf5io_code_snippet]
    hdf5io->open();
    hdf5io->close();
  }
}

Testing the Example Code

To make sure our example code builds and runs correctly, we add it to the unit test suite.

1. Add the new text_examples.cpp file to the add_executable section of the tests/CMakeLists.txt file
2. Rebuild the code as usual with BUILD_TESTING=ON set, e.g., via cmake --build --preset=dev
3. Run the test suite to ensure our example is working, e.g, via ctest --preset=dev

See the Testing 🛡️ section for more details about how to build and run the test suite.

Including Code Examples in Doxygen

To display a code snippet from our example in the documentation we can use the \snippet <file> <label> Doxygen command in our *.dox documentation file. For example to just show the line where we create the HDF5IO object we use:

\snippet tests/examples/test_example.cpp example_hdf5io_code_snippet

which displays as follows in the docs:

    std::unique_ptr<AQNWB::IO::HDF5::HDF5IO> hdf5io =
        std::make_unique<AQNWB::IO::HDF5::HDF5IO>(path);

To add a heading to a code snippet we can use \par command, e.g., \par test_example.cpp to indicate the filename.

Creating Custom Dot Graphs

AqNWB uses Graphviz to improve the quality of the UML diagrams generated by Doxygen. With this, we can also generate custom figures using dot, simply by including the corresponding dot code directly in the doxygen file. For example:

\dot
digraph G {
    node [shape=box];
    AqNWB [label="AqNWB", style=filled, color=lightblue];
    HDF5 [label="HDF5"];
 
    AqNWB -> HDF5 [label="write"];
}
\enddot

to create this figure: