add documentation

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=<Address | Memory | MemoryWithOrigins | Undefined | Thread | Leak | 'Address;Undefined'>`.
+#### Sanitizers
-- **Static Analyzers**, by setting `-DUSE_STATIC_ANALYZER=<clang-tidy | iwyu | cppcheck>`, 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.
+Sanitizers can be enabled by configuring CMake with `-DUSE_SANITIZER=<Address | Memory | MemoryWithOrigins | Undefined | Thread | Leak | 'Address;Undefined'>`.
-- **Ccache**, by setting `-DUSE_CCACHE=<ON | OFF>`.
+
+#### Static Analyzers
+
+Static Analyzers can be enabled by setting `-DUSE_STATIC_ANALYZER=<clang-tidy | iwyu | cppcheck>`, 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=<ON | OFF>`.
 
 ## 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.

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
 )