From dd218a410615bf2004be6a9c131a3d9ed60f3b34 Mon Sep 17 00:00:00 2001
From: Dantali0n <info@dantalion.nl>
Date: Mon, 2 Oct 2023 12:37:21 +0200
Subject: [PATCH] Expand CPP project documentation

---
 .gitlab-ci.yml       |  2 +-
 README.md            | 16 +++++++++++++---
 doc/sphinx/conf.py   |  6 ++++++
 doc/sphinx/index.rst |  5 ++++-
 include/hello.hpp    |  8 +++++++-
 5 files changed, 31 insertions(+), 6 deletions(-)

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index d116b3b..32fd692 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -115,7 +115,7 @@ pages:
     - tar xfz coverage.tar.gz
     # TODO: Add an index page with links to the documentation and coverage.
 
-abi-deplay:
+abi-deploy:
   stage: deploy
   needs: ["versioning", "build-docker-ubuntu-22.04"]
   image: $BASE_IMAGE
diff --git a/README.md b/README.md
index f2a724f..1015fe4 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@ project. The template offers:
 
   - A basic Docker file to be used in the CI
   - A CMake project skeleton
-  - A Doxygen and Sphinx skeleton for documentation
+  - A Doxygen and Sphinx skeleton for documentation, combined with Breathe
   - Formatting scripts for the code
 
 Note: The project is intended to be used for C++ projects without Fortran code.
@@ -24,8 +24,18 @@ project needs to be changed to use `make`.
 
 - Clone the project in the directory `$repo`
 - Install all dependencies as listed in `ci/ubuntu_22_04-base`
-- Create the project: `cmake -DBUILD_TESTING=ON -H$repo -B$repo/build -G Ninja`
-- Build the project: `ninja -C $repo/build`
+- Create build directory: `mkdir build`
+- Create the project: `cmake -DBUILD_TESTING=ON -DBUILD_DOCUMENTATION=ON -B ./build -G Ninja`
+- Build the project: `ninja -C ./build`
+
+Specific targets can also be build on a case per case basis use `ninja -C ./build/ -t targets`
+to list all of them.
+
+For instance:
+- Build the documentation: `ninja -C ./build/ sphinx`
+- Run unit tests: `ninja -C ./build/ test`
+- Install the project globally: ``ninja -C ./build/ install``
+- Clean caches: `ninja -C ./build/ clean`
 
 ## Contributing
 
diff --git a/doc/sphinx/conf.py b/doc/sphinx/conf.py
index 6bfaff1..014ddb5 100644
--- a/doc/sphinx/conf.py
+++ b/doc/sphinx/conf.py
@@ -18,6 +18,12 @@ import sys
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
+
+project = "CPP"
+
+# TODO(): Extract version metadata from CMake and make available in Sphinx
+# version = ""
+
 extensions = [
     "breathe",
 ]
diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst
index 8a7fc4c..b6b063e 100644
--- a/doc/sphinx/index.rst
+++ b/doc/sphinx/index.rst
@@ -6,4 +6,7 @@
 Docs
 ====
 
-.. doxygenfunction:: Hello
+This text is added through ReStructuredText (RST) in Sphinx while the below
+is derived from Doxygen:
+
+.. doxygenindex::
diff --git a/include/hello.hpp b/include/hello.hpp
index a6ff93e..995fcc0 100644
--- a/include/hello.hpp
+++ b/include/hello.hpp
@@ -6,7 +6,13 @@
 
 namespace lib {
 
-/** This function greets the user. */
+/** This function greets the user.
+ *
+ * @code
+ * char *buffer = new char[42];
+ * int charsAdded = sprintf(buffer, "Include code\n", 8);
+ * @endcode
+ */
 void Hello();
 
 } // namespace lib
-- 
GitLab