doxyconfig

Common doxygen config for LizardByte projects.

Overview

This repository provides the common Doxygen configuration used by LizardByte projects. It includes shared Doxygen defaults, Doxygen Awesome styling, custom aliases, and CMake and Read the Docs integration.

🚀 Usage

Important

When using a Markdown file with USE_MDFILE_AS_MAINPAGE, make its first Markdown heading a level 1 heading (# ...). An HTML <h1> does not count. Starting with a level 2 or lower Markdown heading can cause Doxygen to place the main page's sections beneath the next Markdown page in the navigation tree.

1. Add this repository as a submodule to your project.

   git submodule add https://github.com/LizardByte/doxyconfig.git third-party/doxyconfig

2. Place project specific Doxyfile config in ./docs/Doxyfile. You can overwrite anything from the common config here.

3. Add the following to your CMakeLists.txt file.

   option(BUILD_DOCS "Build documentation" ON)
   if(BUILD_DOCS)
       # Set this when the Read the Docs slug differs from the lowercased CMake project name.
       # set(DOXYCONFIG_READTHEDOCS_PROJECT_SLUG your-readthedocs-project)
       add_subdirectory(third-party/doxyconfig docs)
   endif()

   Read the Docs builds use READTHEDOCS_PROJECT automatically. Local CMake builds default to the lowercased top-level project name; set DOXYCONFIG_READTHEDOCS_PROJECT_SLUG when the Read the Docs slug differs.

4. Add the following to your .gitignore file.

   # doxyconfig
   docs/doxyconfig*

5. Optionally, add the following to the input list in your Doxyfile.

   INPUT += ../third-party/doxyconfig/docs/source_code.md
   

6. To build the project on Read the Docs, copy .readthedocs.yaml to the root of your project.

[TOC]