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