Skip to content

Commit 8fb504a

Browse files
aafuleiaafulei
committed
Update MkDocs - Add Technical Details
1 parent d6d1241 commit 8fb504a

4 files changed

Lines changed: 409 additions & 0 deletions

File tree

‎docs/makefile-in-detail.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Makefile in Detail
2+
3+
This note explains two key techniques used in the
4+
[`Makefile`](https://github.com/aafulei/cpp-today/blob/main/Makefile) for this
5+
project:
6+
7+
- Order-only prerequisites
8+
- Dependency (`.d`) files
9+
10+
## Order-Only Prerequisites
11+
12+
The syntax of a typical `make` rule is:
13+
14+
```makefile
15+
target: normal-prerequisites | order-only-prerequisites
16+
recipe
17+
```
18+
19+
An *order-only prerequisite* is a prerequisite that comes after normal
20+
prerequisites, separated by a vertical bar (`|`). Like normal prerequisites,
21+
order-only prerequisites must be built before the main target. However, unlike
22+
normal prerequisites, changes in the timestamps of order-only prerequisites
23+
do *not* trigger rebuilds.
24+
25+
In this
26+
[`Makefile`](https://github.com/aafulei/cpp-today/blob/main/Makefile),
27+
the binary directory `$(BIN_DIR)` is an order-only prerequisite:
28+
29+
```makefile
30+
$(BIN): $(OBJ) | $(BIN_DIR)
31+
```
32+
33+
This rule ensures that the output directory `BIN_DIR` (`./bin/release` or
34+
`./bin/debug`) exists before building the binary `BIN`, but any timestamp
35+
changes in that directory won't cause the binary to be rebuilt.
36+
37+
## Dependency (`.d`) files
38+
39+
`.d` files record header dependencies for each source file, enabling automatic
40+
recompilation when headers change. They serve as an automatic replacement for
41+
explicitly listing headers like:
42+
43+
```makefile
44+
foo.o: foo.cpp foo.hpp
45+
```
46+
47+
With `.d` files, you only need to write:
48+
49+
```makefile
50+
foo.o: foo.cpp
51+
```
52+
53+
and auto-generated `.d` files will handle tracking header dependencies for you.
54+
55+
The [`Makefile`](https://github.com/aafulei/cpp-today/blob/main/Makefile)
56+
for this project generates `.d` files during compilation with:
57+
58+
```makefile
59+
$(BIN_DIR)/%.o: $(SRC_DIR)/%.cpp $(VER_FILE) | $(BIN_DIR)
60+
$(CXX) $(CXXFLAGS) -MMD -MP -c $< -o $@
61+
```
62+
63+
where
64+
65+
- `-MMD` creates `.d` files excluding system headers.
66+
- `-MP` adds phony targets to prevent errors if headers are deleted.
67+
68+
These `.d` files are included via:
69+
70+
```makefile
71+
-include $(DEP)
72+
```
73+
74+
where `$(DEP)` stand for all the dependency files corresponding to source `.cpp`
75+
files (e.g. `today.d` for `today.cpp`). This ensures that changes in header
76+
files trigger necessary recompilation automatically.
77+
78+
*Note that, as a sample project, this project does not necessitate `.d` files
79+
for its own sake; however, we include this technique here since it represents
80+
an industry best practice.*
81+
82+
#### Why the `-MP` Option?
83+
84+
The `-MP` option causes the compiler to generate phony targets for all relevant
85+
header files in the `.d` files. This prevents `make` from failing if some
86+
headers are deleted later, since the phony targets act as placeholders for the
87+
missing files, allowing the build to proceed without errors.
88+
89+
#### Role of `-include $(DEP)`
90+
91+
The `-include` directive includes `.d` dependency files *if they exist*, but
92+
suppresses errors if they don't. The leading `-` tells `make` to ignore missing
93+
files instead of failing, which is important the first time the project is
94+
built before any `.d` files are generated.
95+
96+
---
97+
98+
*For source code and project files, please see the
99+
[GitHub repository](https://github.com/aafulei/cpp-today).*

‎docs/ready-for-deployment.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
# Ready for Deployment
2+
3+
![](./img/project.png)
4+
5+
As illustrated in the above diagram, this project provides two types of online
6+
resources to support users and developers:
7+
8+
- [MkDocs project website](https://aafulei.github.io/cpp-today/)
9+
- [Doxygen source code documentation](https://aafulei.github.io/cpp-today/doxygen/html/)
10+
11+
MkDocs website hosts user guides and general project documentation, while
12+
Doxygen pages offer detailed source code documentation for reference.
13+
14+
This document outlines the basic steps to deploy these two websites.
15+
16+
## Deploy MkDocs Website
17+
18+
### 1. Set up Environment
19+
20+
Create a Python virtual environment at the root of the project to isolate
21+
dependencies:
22+
23+
```shell
24+
python -m venv venv
25+
```
26+
27+
Activate the virtual environment:
28+
29+
```shell
30+
source venv/bin/activate
31+
```
32+
33+
Install [MkDocs](https://www.mkdocs.org/) and the
34+
[Material](https://squidfunk.github.io/mkdocs-material/) theme:
35+
36+
```shell
37+
pip install mkdocs mkdocs-material
38+
```
39+
40+
### 2. Configure
41+
42+
Modify [`mkdocs.yml`](https://github.com/aafulei/cpp-today/blob/main/mkdocs.yml)
43+
to configure the project website. Most options are well documented at the
44+
MkDocs and Material websites. The additional
45+
[`docs/css/custom-mkdocs.css`](https://github.com/aafulei/cpp-today/blob/main/docs/css/custom-mkdocs.css)
46+
file increases the font size for tables in Markdown files.
47+
48+
### 3. Preview
49+
50+
To preview the MkDocs project website locally, run:
51+
52+
```shell
53+
mkdocs serve
54+
```
55+
56+
MkDocs includes a live preview server accessible at
57+
[http://127.0.0.1:8000](http://127.0.0.1:8000) that allows you to preview your
58+
changes as you write documentation. Any changes to the `mkdocs.yml`
59+
configuration file and markdown files inside the
60+
[`docs`](https://github.com/aafulei/cpp-today/blob/main/docs/)
61+
directory will be reflected in real time.
62+
63+
### 4. Deploy
64+
65+
To deploy the MkDocs project website, run:
66+
67+
```shell
68+
mkdocs gh-deploy
69+
```
70+
71+
MkDocs will build the source files in the `docs` directory into a static site
72+
inside the `site` directory (in
73+
[`.gitignore`](https://github.com/aafulei/cpp-today/blob/main/.gitignore)).
74+
It will then deploy this `site` to the
75+
[`gh-pages`](https://github.com/aafulei/cpp-today/tree/gh-pages)
76+
branch of the GitHub repository. GitHub Pages will handle updates and render the
77+
project website.
78+
79+
## Deploy Doxygen Documentation
80+
81+
### 1. Set up Environment
82+
83+
On macOS, install Doxygen by running
84+
85+
```shell
86+
brew install doxygen
87+
```
88+
89+
Generate a template configuration file:
90+
91+
```shell
92+
doxygen -g Doxygen.original
93+
```
94+
95+
Generate a template layout file:
96+
97+
```shell
98+
doxygen -l DoxygenLayout.original.xml
99+
```
100+
101+
Do not edit these original files directly (add them to `.gitignore`). Instead,
102+
make copies for editing, which makes it easier to track changes later:
103+
104+
```shell
105+
cp Doxyfile.original Doxyfile
106+
cp DoxygenLayout.original.xml DoxygenLayout.xml
107+
```
108+
109+
### 2. Configure Docs Generation
110+
111+
Modify the
112+
[`Doxyfile`](https://github.com/aafulei/cpp-today/blob/main/Doxyfile)
113+
to configure documentation generation. To review your changes, run:
114+
115+
```shell
116+
diff Doxyfile.original Doxyfile
117+
```
118+
119+
For this project, the modified settings are:
120+
121+
| Key | Value |
122+
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------- |
123+
| `PROJECT_NAME` | "CppToday" |
124+
| `PROJECT_BRIEF` | "What day is it today? A minimal C++23 program." |
125+
| `PROJECT_LOGO` | [`docs/img/logo-doxygen.svg`](https://github.com/aafulei/cpp-today/blob/main/docs/img/logo-doxygen.svg) |
126+
| `PROJECT_ICON` | [`docs/img/icon.svg`](https://github.com/aafulei/cpp-today/blob/main/docs/img/icon.svg) |
127+
| `OUTPUT_DIRECTORY` | `docs/doxygen` (in `.gitignore`) |
128+
| `LAYOUT_FILE` | [`DoxygenLayout.xml`](https://github.com/aafulei/cpp-today/blob/main/DoxygenLayout.xml) (see below) |
129+
| `INPUT` | [`src`](https://github.com/aafulei/cpp-today/blob/main/src/) |
130+
| `RECURSIVE` | `YES` (will look recusrively into `src`) |
131+
| `EXCLUDE` | [`tests`](https://github.com/aafulei/cpp-today/blob/main/tests/) |
132+
| `HTML_EXTRA_STYLESHEET` | [`docs/css/custom-doxygen.css`](https://github.com/aafulei/cpp-today/blob/main/docs/css/custom-doxygen.css) (see below) |
133+
| `DISABLE_INDEX` | `NO` (will show horizontal tabs at top) |
134+
| `HTML_FORMULA_FORMAT` | `svg` (instead of `png`; requires [Inkscape](https://inkscape.org/)) |
135+
| `GENERATE_LATEX` | `NO` |
136+
| `HAVE_DOT` | `YES` (requires [Graphviz](https://graphviz.org/download/), for `svg`) |
137+
| `CALL_GRAPH` | `YES` |
138+
| `CALLER_GRAPH` | `YES` |
139+
| `DOT_IMAGE_FORMAT` | `svg` (instead of `png`, for nicer look) |
140+
141+
The most important setting for Doxygen is `INPUT`, which tells Doxygen to look
142+
into the `src` directory and its subdirectories, parsing code and comments to
143+
generate corresponding documentation.
144+
145+
The extra
146+
[`docs/css/custom-doxygen.css`](https://github.com/aafulei/cpp-today/blob/main/docs/css/custom-doxygen.css)
147+
removes the panel synchronization button from the Doxygen website, which the
148+
author finds distracting.
149+
150+
### 3. Configure Layout
151+
152+
Edit
153+
[`DoxygenLayout.xml`](https://github.com/aafulei/cpp-today/blob/main/DoxygenLayout.xml)
154+
to customize the layout for Doxygen pages. To see your changes, run:
155+
156+
```shell
157+
diff DoxygenLayout.original.xml DoxygenLayout.xml
158+
```
159+
160+
In this project, the following lines were added to the `<navindex>` element to
161+
add two tabs for quick navigation to the GitHub repository and the MkDocs
162+
project website:
163+
164+
```xml
165+
<tab type="user" url="http://github.com/aafulei/cpp-today/" title="GitHub"/>
166+
<tab type="user" url="../../" title="Back to Project Website"/>
167+
```
168+
169+
### 4. Deploy
170+
171+
Because MkDocs manages the entire `docs` directory and Doxygen outputs HTML
172+
files inside `docs/doxygen`, no additional deployment steps are needed. Running:
173+
174+
```shell
175+
mkdocs gh-deploy
176+
```
177+
178+
will deploy both the MkDocs site and the Doxygen-generated pages as part of
179+
the overall project website.
180+
181+
---
182+
183+
*For source code and project files, please see the
184+
[GitHub repository](https://github.com/aafulei/cpp-today).*

0 commit comments

Comments
 (0)