From 6df5e095c9b75d66aec89fbc7755a3527d7f21a2 Mon Sep 17 00:00:00 2001 From: Lars Melchior Date: Wed, 3 Jun 2020 14:06:56 +0200 Subject: [PATCH] add documentation --- README.md | 36 +++++++++++++++++++++++++++++------- documentation/CMakeLists.txt | 2 +- 2 files changed, 30 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 079be2e..a92c59e 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,8 @@ This template is the result of learnings from many previous projects and should - Code formatting enforced by [clang-format](https://clang.llvm.org/docs/ClangFormat.html) via [Format.cmake](https://github.com/TheLartians/Format.cmake) - Reproducible dependency management via [CPM.cmake](https://github.com/TheLartians/CPM.cmake) - Installable target with versioning information via [PackageProject.cmake](https://github.com/TheLartians/PackageProject.cmake) -- Support for [sanitizer tools and more](#additional-tools) +- Automatic documentation generation with [Doxygen](https://www.doxygen.nl) +- Support for [sanitizer tools, and more](#additional-tools) ## Usage @@ -81,14 +82,35 @@ cmake --build build/test --target fix-format See [Format.cmake](https://github.com/TheLartians/Format.cmake) for more options. +### Build the documentation + +The documentation is automatically built and updated after every [release](https://help.github.com/en/github/administering-a-repository/managing-releases-in-a-repository). +To manually build documentation, call the following command. + +```bash +cmake -Hdocumentation -Bbuild/doc +cmake --build build/doc --target GenerateDocs +# view the docs (using `open` on Mac) +open build/doc/doxygen/html/index.html +``` + ### Additional tools The test and standalone subprojects include the [tools.cmake](cmake/tools.cmake) file which is used to import additional tools on-demand through CMake configuration arguments. The following are currently supported. -- **Sanitizers**, by setting `-DUSE_SANITIZER=
`. -- **Static Analyzers**, by setting `-DUSE_STATIC_ANALYZER=`, or a combination of those in quotation marks, separated by semicolons. Arguments can be passed to the analyzers by setting the `CLANG_TIDY_ARGS`, `IWYU_ARGS` or `CPPCHECK_ARGS` variables. -- **Ccache**, by setting `-DUSE_CCACHE=`. +#### Sanitizers +Sanitizers can be enabled by configuring CMake with `-DUSE_SANITIZER=
`. + +#### Static Analyzers + +Static Analyzers can be enabled by setting `-DUSE_STATIC_ANALYZER=`, or a combination of those in quotation marks, separated by semicolons. +By default, analyzers will automatically find configuration files such as `.clang-format`. +Additional arguments can be passed to the analyzers by setting the `CLANG_TIDY_ARGS`, `IWYU_ARGS` or `CPPCHECK_ARGS` variables. + +#### Ccache + +Ccache can be enabled by configuring with `-DUSE_CCACHE=`. ## FAQ @@ -97,9 +119,9 @@ The following are currently supported. Yes, however you will need to change the library type to an `INTERFACE` library as documented in the [CMakeLists.txt](CMakeLists.txt). See [here](https://github.com/TheLartians/StaticTypeInfo) for an example header-only library based on the template. -> I don't need a standalone target. How can I get rid of it? +> I don't need a standalone target / documentation. How can I get rid of it? -Simply remove the standalone directory and github workflow file. +Simply remove the standalone / documentation directory and according github workflow file. > I see you are using `GLOB` to add source files in CMakeLists.txt. Isn't that evil? @@ -108,7 +130,7 @@ Glob is considered bad because any changes to the source file structure [might n > I want create additional targets that depend on my library. Should I modify the main CMakeLists to include them? -Always avoid including derived projects from the libraries CMakeLists (even though it is a common sight in the C++ world), as this effectively inverts the dependency tree and makes the build system hard to reason about. +Avoid including derived projects from the libraries CMakeLists (even though it is a common sight in the C++ world), as this effectively inverts the dependency tree and makes the build system hard to reason about. Instead, create a new directory or project with a CMakeLists that adds the library as a dependency (e.g. like the [standalone](standalone/CMakeLists.txt) directory). Depending type it might make sense move these components into a separate repositories and reference a specific commit or version of the library. This has the advantage that individual libraries and components can be improved and updated independently. diff --git a/documentation/CMakeLists.txt b/documentation/CMakeLists.txt index 5f9bf38..0a16fb9 100644 --- a/documentation/CMakeLists.txt +++ b/documentation/CMakeLists.txt @@ -31,6 +31,6 @@ set(DOXYGEN_PROJECT_ROOT "${CMAKE_CURRENT_LIST_DIR}/..") build_docs( TARGET_NAME GenerateDocs DOXYFILE_PATH ${CMAKE_CURRENT_LIST_DIR}/Doxyfile - OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/doc + OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/doxygen PROCESS_DOXYFILE ON )