As illustrated in the above diagram, this project provides two types of online resources to support users and developers:
MkDocs website hosts user guides and general project documentation, while Doxygen pages offer detailed source code documentation for reference.
This document outlines the basic steps to deploy these two websites.
Create a Python virtual environment at the root of the project to isolate dependencies:
python -m venv venvActivate the virtual environment:
source venv/bin/activateInstall MkDocs and the Material theme:
pip install mkdocs mkdocs-materialModify mkdocs.yml
to configure the project website. Most options are well documented at the
MkDocs and Material websites. The additional
docs/css/custom-mkdocs.css
file increases the font size for tables in Markdown files.
To preview the MkDocs project website locally, run:
mkdocs serveMkDocs includes a live preview server accessible at
http://127.0.0.1:8000 that allows you to preview your
changes as you write documentation. Any changes to the mkdocs.yml
configuration file and markdown files inside the
docs
directory will be reflected in real time.
To deploy the MkDocs project website, run:
mkdocs gh-deployMkDocs will build the source files in the docs directory into a static site
inside the site directory (in
.gitignore).
It will then deploy this site to the
gh-pages
branch of the GitHub repository. GitHub Pages will handle updates and render the
project website.
On macOS, install Doxygen by running
brew install doxygenGenerate a template configuration file:
doxygen -g Doxygen.originalGenerate a template layout file:
doxygen -l DoxygenLayout.original.xmlDo not edit these original files directly (add them to .gitignore). Instead,
make copies for editing, which makes it easier to track changes later:
cp Doxyfile.original Doxyfile
cp DoxygenLayout.original.xml DoxygenLayout.xmlModify the
Doxyfile
to configure documentation generation. To review your changes, run:
diff Doxyfile.original DoxyfileFor this project, the modified settings are:
| Key | Value |
|---|---|
PROJECT_NAME |
"CppToday" |
PROJECT_BRIEF |
"What day is it today? A minimal C++23 program." |
PROJECT_LOGO |
docs/img/logo-doxygen.svg |
PROJECT_ICON |
docs/img/icon.svg |
OUTPUT_DIRECTORY |
docs/doxygen (in .gitignore) |
LAYOUT_FILE |
DoxygenLayout.xml (see below) |
INPUT |
src |
RECURSIVE |
YES (will look recusrively into src) |
EXCLUDE |
tests |
HTML_EXTRA_STYLESHEET |
docs/css/custom-doxygen.css (see below) |
DISABLE_INDEX |
NO (will show horizontal tabs at top) |
HTML_FORMULA_FORMAT |
svg (instead of png; requires Inkscape) |
GENERATE_LATEX |
NO |
HAVE_DOT |
YES (requires Graphviz, for svg) |
CALL_GRAPH |
YES |
CALLER_GRAPH |
YES |
DOT_IMAGE_FORMAT |
svg (instead of png, for nicer look) |
The most important setting for Doxygen is INPUT, which tells Doxygen to look
into the src directory and its subdirectories, parsing code and comments to
generate corresponding documentation.
The extra
docs/css/custom-doxygen.css
removes the panel synchronization button from the Doxygen website, which the
author finds distracting.
Edit
DoxygenLayout.xml
to customize the layout for Doxygen pages. To see your changes, run:
diff DoxygenLayout.original.xml DoxygenLayout.xmlIn this project, the following lines were added to the <navindex> element to
add two tabs for quick navigation to the GitHub repository and the MkDocs
project website:
<tab type="user" url="http://github.com/aafulei/cpp-today/" title="GitHub"/>
<tab type="user" url="../../" title="Back to Project Website"/>Because MkDocs manages the entire docs directory and Doxygen outputs HTML
files inside docs/doxygen, no additional deployment steps are needed. Running:
mkdocs gh-deploywill deploy both the MkDocs site and the Doxygen-generated pages as part of the overall project website.
For source code and project files, please see the GitHub repository.