From d660b60cf4e829147663bc48f70f856c5d111c14 Mon Sep 17 00:00:00 2001
From: Oliver Ruebel <oruebel@lbl.gov>
Date: Sat, 24 Aug 2024 19:47:39 -0700
Subject: [PATCH] Add documentation on how to write Documentation in Doxygen

---
 docs/pages/2_devdocs.dox             |   1 +
 docs/pages/devdocs/documentation.dox | 117 +++++++++++++++++++++++++++
 tests/CMakeLists.txt                 |   3 +-
 tests/examples/test_example.cpp      |  18 +++++
 4 files changed, 138 insertions(+), 1 deletion(-)
 create mode 100644 docs/pages/devdocs/documentation.dox
 create mode 100644 tests/examples/test_example.cpp

diff --git a/docs/pages/2_devdocs.dox b/docs/pages/2_devdocs.dox
index 415903d3..7b868d38 100644
--- a/docs/pages/2_devdocs.dox
+++ b/docs/pages/2_devdocs.dox
@@ -5,6 +5,7 @@
  *
  * - @subpage dev_install_page
  * - @subpage testing
+ * - @subpage dev_docs_page
  * - @subpage code_of_conduct_page
  * - @subpage license_page
  * - @subpage copyright_page
diff --git a/docs/pages/devdocs/documentation.dox b/docs/pages/devdocs/documentation.dox
new file mode 100644
index 00000000..a86453d8
--- /dev/null
+++ b/docs/pages/devdocs/documentation.dox
@@ -0,0 +1,117 @@
+/**
+ * @page dev_docs_page Documentation
+ *
+ * AqNWB uses [Doxygen](https://www.doxygen.nl/) with  [Graphviz](https://graphviz.org/) for
+ * documentation. The ``cmake`` related instructions on this page follow the
+ * \ref devbuild_presets_subsec "Developer Presets" installation instructions using the ``dev`` preset.
+ *
+ * \section dev_docs_requirements_sec Building the Docs
+ *
+ * 1. Ensure that [Doxygen](https://www.doxygen.nl/) and [Graphviz](https://graphviz.org/) 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``
+ *
+ * \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).
+ *
+ * \section dev_docs_creating Creating New Documentation Pages
+ *
+ * To create a new page as part of the \ref userdocs docs, simply create a new ``.dox`` file in the
+ * ``docs/pages/userdocs`` folder, e.g.:
+ *
+ * \par **docs/pages/userdocs/mypage.dox**
+ * \code{.sh}
+ * /**
+ * * @page mypage My New Page
+ * *
+ * */
+ * \endcode
+ *
+ * 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  \ref devdocs docs by adding a new ``.dox`` file to the ``docs/pages/devdocs``
+ * and including it as as subpage in ``docs/pages/2_devdocs.dox``.
+ *
+ * \section dev_docs_codeexamples_sec Creating Code Examples
+ *
+ * Code examples are defined as part of the \ref testing "unit tests" to ensure code examples used in the
+ * documentation are tested and work as expected.
+ *
+ * \subsection dev_docs_codeexamples_def_sec 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 sinppets.
+ *
+ * \par test_example.cpp
+ * \snippet tests/examples/test_example.cpp example_all
+ *
+ * \subsection  dev_docs_codeexamples_run_sec 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 \ref testing section for more details about how to build and run the test suite.
+ *
+ *  \subsection  dev_docs_codeexamples_incl_sec 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 \ref AQNWB::HDF5::HDF5IO "HDF5IO
+ *  object we use:
+ *
+ * \code{.sh}
+ *  \snippet tests/examples/test_example.cpp example_hdf5io_code_snippet``
+ * \endcode
+ *
+ * which displays as follows in the docs:
+ *
+ * \snippet tests/examples/test_example.cpp example_hdf5io_code_snippet
+ *
+ * To add a heading to a code snippet we can use ``\par`` command, e.g., ``\par test_example.cpp``
+ * to indicate the filename.
+ *
+ *
+ * \section dev_docs_graphviz_sec Creating Custom Dot Graphs
+ *
+ * AqNWB uses  [Graphviz](https://graphviz.org/) to improve the quality of
+ * the UML diagrams generated by [Doxygen](https://www.doxygen.nl/). With this, we
+ * can also generate custom figures using `dot`, simply by including the corresponding
+ * dot code directly in the doxygen file. For example:
+ *
+ * \code{.sh}
+ * \dot
+ * digraph G {
+ *     node [shape=box];
+ *     AqNWB [label="AqNWB", style=filled, color=lightblue];
+ *     HDF5 [label="HDF5"];
+ *
+ *     AqNWB -> HDF5 [label="write"];
+ * }
+ * \enddot
+ * \endcode
+ *
+ * to create this figure:
+ *
+ * \dot
+ * digraph G {
+ *     node [shape=box];
+ *     AqNWB [label="AqNWB", style=filled, color=lightblue];
+ *     HDF5 [label="HDF5"];
+ *
+ *     AqNWB -> HDF5 [label="write"];
+ * }
+ * \enddot
+ *
+ */
+
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index 08c30bf2..d5ff6e39 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -18,7 +18,8 @@ add_executable(aq-nwb_test
     testHDF5IO.cpp
     testNWBFile.cpp
     testNWBRecording.cpp
-    examples/test_HDF5IO_examples.cpp  # Include examples source file
+    examples/test_HDF5IO_examples.cpp
+    examples/test_example.cpp
 )
 
 # Ensure the aq-nwb_test target can include headers from the current directory and Catch2
diff --git a/tests/examples/test_example.cpp b/tests/examples/test_example.cpp
new file mode 100644
index 00000000..c4ee5b3f
--- /dev/null
+++ b/tests/examples/test_example.cpp
@@ -0,0 +1,18 @@
+// [example_all]
+#include <catch2/catch_test_macros.hpp>
+#include "hdf5/HDF5IO.hpp"
+#include "testUtils.hpp"
+
+TEST_CASE("SimpleExamples", "[hdf5io]")
+{
+  SECTION("docsExample")
+  {
+    std::string path = getTestFilePath("testWithSWMRMode.h5");
+    // [example_hdf5io_code_snippet]
+    std::unique_ptr<AQNWB::HDF5::HDF5IO> hdf5io = std::make_unique<AQNWB::HDF5::HDF5IO>(path);
+     // [example_hdf5io_code_snippet]
+    hdf5io->open();
+    hdf5io->close();
+  }
+}
+// [example_all]