Expand CPP project documentation

.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

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
 

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",
 ]

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::

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