Merge pull request #190 from imperialCHEPI/dont_build_docs_by_default

Don't build docs by default

.github/workflows/ci.yml

@@ -116,7 +116,8 @@ jobs:
       - name: Build HealthGPS (release)
         if: "!cancelled()" # Run this step, even if the previous one fails
         run: |
-          cmake --preset=${{ matrix.platform }}-release -DWARNINGS_AS_ERRORS=ON
+          # Build documentation so we can show Doxygen warnings
+          cmake --preset=${{ matrix.platform }}-release -DWARNINGS_AS_ERRORS=ON -DBUILD_DOC=ON
           cmake --build --preset=release-build-${{ matrix.platform }} --target=install
 
       - name: Upload artifacts

.github/workflows/docs.yml

@@ -49,7 +49,7 @@ jobs:
           ./bootstrap-vcpkg.sh -disableMetrics
       - name: Configure HealthGPS
         run: |
-          cmake --preset=linux-release
+          cmake --preset=linux-release -DBUILD_DOC=ON
       - name: Build with doxygen
         run: |
           ninja -C out/build/linux-release/ doxygen-docs

CMakeLists.txt

@@ -1,6 +1,6 @@
 cmake_minimum_required (VERSION 3.20)
 
-option(BUILD_DOC "Build API documentation" ON)
+option(BUILD_DOC "Build API documentation" OFF)
 option(WARNINGS_AS_ERRORS "Make the build fail if the compiler gives a warning" OFF)
 
 # minimum default standard

docs/development.md

@@ -67,9 +67,25 @@ cmake --build --preset='debug-build-linux'
 ctest --preset='core-test-linux'
 ```
 
-All available options are defined using CMake *presets* in the `CMakePresets.json` file, which also declare *build presets* and other options previously provided to [CMake](https://cmake.org/) via command line arguments. The use of *presets* provides consistent build scripts across development and CI/CD environments using source control for reproducibility.
+All available options are defined using CMake *presets* in the `CMakePresets.json` file, which also
+declare *build presets* and other options previously provided to [CMake](https://cmake.org/) via
+command line arguments. The use of *presets* provides consistent build scripts across development
+and CI/CD environments using source control for reproducibility.
 
-## Optional: Running `pre-commit` hooks
+## Building documentation
+
+Technical documentation for the latest version of Health-GPS [is available on the
+website](https://imperialchepi.github.io/healthgps/).
+
+If you wish to build documentation locally, you need [Doxygen](https://www.doxygen.nl/) installed.
+
+You must enable the `BUILD_DOC` CMake option, e.g.:
+
+```cmd
+> cmake --preset=linux-debug -DBUILD_DOC=ON
+```
+
+## Running `pre-commit` hooks
 
 It is recommended that developers install [`pre-commit`](https://pre-commit.com/) to
 make use of [the hooks](./.pre-commit-config.yaml) we have installed for this
@@ -85,7 +101,7 @@ install the hooks into your local clone of the Health-GPS repository, like so:
 Now, every time attempt to make a git commit, your changes will be checked against the
 `pre-commit` hooks.
 
-## Optional: Performing static analysis with `clang-tidy`
+## Performing static analysis with `clang-tidy`
 
 [`clang-tidy`] is a static analysis tool based on clang, which can identify bugs and
 stylistic problems with C++ code. It comes with a helper script, `run-clang-tidy`, which

src/CMakeLists.txt

@@ -13,7 +13,7 @@ if (BUILD_TESTING)
 	add_subdirectory (HealthGPS.Tests)
 endif()
 
-if (BUILD_DOC AND CMAKE_BUILD_TYPE MATCHES "^[Rr]elease")
+if (BUILD_DOC)
     message(STATUS "Doxygen build folder: ${CMAKE_CURRENT_BINARY_DIR}")
 	set(DOXYGEN_FILE_PATTERNS *.h *.cpp *.md)
 	set(DOXYGEN_EXCLUDE_PATTERNS "*/vcpkg_installed/*" "*/_deps/" "*/docs/*" "*/external/*" "*/HealthGPS.Tests/*")