You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This page contains information for contributors to the Mr.Docs project.
4
-
It is intended to provide an overview of the codebase and the process of adding new features.
5
-
6
-
Before sending changes, run `python util/run_all_tests.py`.
7
-
This script is treated as a “source of truth” pass that configures the preferred preset, builds, runs golden + unit + lint/schema/self-doc checks, installs into a local `install/<preset>` prefix, and (by default) builds docs using that fresh install.
8
-
Not every policy can be enforced programmatically, but this script covers the checks that are automated; prefer it over ad-hoc command sequences.
9
-
Use `--skip-docs` to omit docs or `--no-strict` to relax strict warning handling when needed.
10
-
11
-
== Codebase Overview
12
-
13
-
The Mr.Docs codebase is divided into several modules:
14
-
15
-
include::partial$workflow.adoc[]
16
-
17
-
This section provides an overview of each module and how they interact with each other in the Mr.Docs codebase.
1
+
= Options & architecture
18
2
19
3
[#options]
20
-
=== Parsing options
4
+
== Parsing options
21
5
22
6
Mr.Docs options affect the behavior of the compilation database, how symbols are extracted, and how the documentation is generated.
23
7
They are parsed from the command line and configuration file.
@@ -26,12 +10,12 @@ The main entry point of Mr.Docs is the `DoGenerateAction` function in `src/tool/
26
10
It loads the options, creates the compilation database, and runs the extraction and generation steps.
27
11
The options are formed from a combination of command line arguments and configuration file settings.
28
12
29
-
==== Command Line Options
13
+
=== Command Line Options
30
14
31
15
Command line and common options are defined in `src/tool/ToolArgs.hpp`.
32
16
The `ToolArgs` class uses the `llvm::cl` library to define and parse the command line arguments.
33
17
34
-
==== Configuration File
18
+
=== Configuration File
35
19
36
20
Common options are defined in `mrdocs/Config.hpp`.
37
21
The `Config` class represents all public options that could be defined in a configuration file.
@@ -41,7 +25,7 @@ The function `mrdocs::loadConfig` is also provided to parse all public options f
41
25
42
26
Internally, Mr.Docs uses the derived `mrdocs::ConfigImpl` class (`src/lib/Lib/ConfigImpl.hpp`) to also store the private representation of parsed options, such as filters.
43
27
44
-
==== Finalizing Options
28
+
=== Finalizing Options
45
29
46
30
Common options are stored in the `Config` class, while the `ToolArgs` class stores common options and the command line options.
47
31
For instance, the `config` option can only be set from the command line, as it would be illogical to expect the location of the configuration file to be defined in the configuration file itself.
@@ -172,129 +156,4 @@ Documentation generators are responsible for traversing the corpus and generatin
172
156
173
157
The API for documentation generators is defined in `mrdocs/Generator.hpp`.
174
158
175
-
=== Directory Layout
176
-
177
-
The MrDocs codebase is organized as follows:
178
-
179
-
==== `include/`—The main include directory
180
-
181
-
This directory contains the public headers for the MrDocs library.
182
-
183
-
* `include/mrdocs/`—The core library headers
184
-
** `include/mrdocs/ADT`—Data Structures
185
-
** `include/mrdocs/Dom`—The Document Object Model for Abstract Trees
186
-
** `include/mrdocs/Metadata`—`Symbol` nodes and metadata classes
** `docs/extensions`—Antora extensions for the documentation
222
-
223
-
==== `third-party/`—Helpers for third-party libraries
224
-
225
-
This directory contains build scripts and configuration files for third-party libraries.
226
-
227
-
* `third-party/`—Third-party libraries
228
-
** `third-party/llvm/`—CMake Presets for LLVM
229
-
** `third-party/duktape/`—CMake scripts for Duktape
230
-
** `third-party/lua/`—A bundled Lua interpreter
231
-
232
159
== Polymorphism
233
-
234
-
== Coding Standards
235
-
236
-
=== Paths
237
-
238
-
The AST visitor and metadata all use forward slashes to represent file pathnames, even on Windows.
239
-
This is so the generated reference documentation does not vary based on the platform.
240
-
241
-
=== Exceptions
242
-
243
-
Errors thrown by the program should always have type `Exception`.
244
-
Objects of this type are capable of transporting an `Error` object.
245
-
This is important for the scripting to work; exceptions are used to propagate errors from library code to scripts and back to the invoking code.
246
-
For exceptional cases, these thrown exceptions should be uncaught.
247
-
The tool installs an uncaught exception handler that prints a stack trace and exits the process immediately.
248
-
249
-
=== Testing
250
-
251
-
All new features should be accompanied by tests.
252
-
The `mrdocs-test` target is used to run the test suites.
253
-
This target has its entry point in `src/test/TestMain.cpp`, which can take two paths:
254
-
255
-
* Golden testing: When input paths are provided to the test executable via the command line, the test suite will run the `DoTestAction()` that iterates all files in `test-files` comparing the input source files with the expected XML output files.
256
-
* Unit testing: When no input paths are provided, all unit tests will be run via `unit_test_main()`, defined by our test-suite library in `src/test_suite/test_suite.cpp`.
257
-
258
-
The fixtures for golden testing are defined in `test-files/golden-tests`, where files in each directory have the following format:
259
-
260
-
* `mrdocs.yml`: Basic configuration options for all files in this directory.
261
-
* `<filename>.cpp`: The input source file to extract symbols from.
262
-
* `<filename>.xml`: The expected XML output file generated with the XML generator.
263
-
* `<filename>.bad.xml`: The test output file generated when the test fails.
264
-
* `<filename>.yml`: Extra configuration options for this specific file.
265
-
266
-
Multipage golden tests follow a snapshot-based layout:
267
-
268
-
* The suite defaults to `multipage: false` in `test-files/golden-tests/mrdocs.yml`; a multipage test must provide a `<stem>.yml` that sets `multipage: true`.
269
-
* Expected output lives under `<stem>.multipage/<format>/...` (one directory per generator); single-page siblings like `<stem>.html`/`.xml` must be absent.
270
-
* The harness skips `.multipage/` directories during discovery and compares generated temp output trees to the snapshot (strict tree + content).
271
-
* Add a short comment in the `.cpp` explaining why multipage is required—use it only when single-page output cannot validate the behavior (e.g., relative asset/link handling).
272
-
273
-
== Style Guide
274
-
275
-
This project follows informal formatting conventions established by previous Boost projects.
276
-
To help contributors, we provide a `.clang-format` file that encodes these rules.
277
-
278
-
* Do *not* apply clang-format across entire files or the whole project.
279
-
* Use the config only as a *reference* for your IDE/editor, or to format the code you **personally add or modify** in a commit.
280
-
* Always check the surrounding code and keep consistent with it.
281
-
* Do not create style-only commits that introduce large diffs without functional changes.
282
-
283
-
Why This Approach:
284
-
285
-
* Keeps history clean: avoids large, style-only commits.
286
-
* Ensures new contributors are not lost when adapting to project style.
287
-
* Encourages consistency without rigid automation.
288
-
289
-
General Advice: When in doubt, copy the style of the surrounding code.
290
-
The `.clang-format` file is a tool to help you, not a rule to enforce blindly.
291
-
292
-
The utility script `./util/reformat.sh` can also be used to check a few project invariants, such as header guards and include order.
293
-
294
-
== Contributing
295
-
296
-
If you find a bug or have a feature request, please open an issue on the MrDocs GitHub repository: https://github.com/cppalliance/mrdocs/issues
297
-
298
-
If you would like to contribute a feature or bug fix, please open a pull request on the MrDocs GitHub repository: https://github.com/cppalliance/mrdocs/pulls
299
-
300
-
If you would like to discuss a feature or bug fix before opening a pull request, discussing happen in the `#mrdocs` channel on the Cpplang Slack: https://cpplang.slack.com/
This page contains information for contributors to the Mr.Docs project.
4
+
It is intended to provide an overview of the codebase and the process of adding new features.
5
+
6
+
Before sending changes, run `python util/run_all_tests.py`.
7
+
This script is treated as a “source of truth” pass that configures the preferred preset, builds, runs golden + unit + lint/schema/self-doc checks, installs into a local `install/<preset>` prefix, and (by default) builds docs using that fresh install.
8
+
Not every policy can be enforced programmatically, but this script covers the checks that are automated; prefer it over ad-hoc command sequences.
9
+
Use `--skip-docs` to omit docs or `--no-strict` to relax strict warning handling when needed.
The `mrdocs-test` target is used to run the test suites.
5
+
This target has its entry point in `src/test/TestMain.cpp`, which can take two paths:
6
+
7
+
* Golden testing: When input paths are provided to the test executable via the command line, the test suite will run the `DoTestAction()` that iterates all files in `test-files` comparing the input source files with the expected XML output files.
8
+
* Unit testing: When no input paths are provided, all unit tests will be run via `unit_test_main()`, defined by our test-suite library in `src/test_suite/test_suite.cpp`.
9
+
10
+
The fixtures for golden testing are defined in `test-files/golden-tests`, where files in each directory have the following format:
11
+
12
+
* `mrdocs.yml`: Basic configuration options for all files in this directory.
13
+
* `<filename>.cpp`: The input source file to extract symbols from.
14
+
* `<filename>.xml`: The expected XML output file generated with the XML generator.
15
+
* `<filename>.bad.xml`: The test output file generated when the test fails.
16
+
* `<filename>.yml`: Extra configuration options for this specific file.
17
+
18
+
Multipage golden tests follow a snapshot-based layout:
19
+
20
+
* The suite defaults to `multipage: false` in `test-files/golden-tests/mrdocs.yml`; a multipage test must provide a `<stem>.yml` that sets `multipage: true`.
21
+
* Expected output lives under `<stem>.multipage/<format>/...` (one directory per generator); single-page siblings like `<stem>.html`/`.xml` must be absent.
22
+
* The harness skips `.multipage/` directories during discovery and compares generated temp output trees to the snapshot (strict tree + content).
23
+
* Add a short comment in the `.cpp` explaining why multipage is required—use it only when single-page output cannot validate the behavior (e.g., relative asset/link handling).
The AST visitor and metadata all use forward slashes to represent file pathnames, even on Windows.
8
+
This is so the generated reference documentation does not vary based on the platform.
9
+
10
+
=== Exceptions
11
+
12
+
Errors thrown by the program should always have type `Exception`.
13
+
Objects of this type are capable of transporting an `Error` object.
14
+
This is important for the scripting to work; exceptions are used to propagate errors from library code to scripts and back to the invoking code.
15
+
For exceptional cases, these thrown exceptions should be uncaught.
16
+
The tool installs an uncaught exception handler that prints a stack trace and exits the process immediately.
17
+
18
+
== Style Guide
19
+
20
+
This project follows informal formatting conventions established by previous Boost projects.
21
+
To help contributors, we provide a `.clang-format` file that encodes these rules.
22
+
23
+
* Do *not* apply clang-format across entire files or the whole project.
24
+
* Use the config only as a *reference* for your IDE/editor, or to format the code you **personally add or modify** in a commit.
25
+
* Always check the surrounding code and keep consistent with it.
26
+
* Do not create style-only commits that introduce large diffs without functional changes.
27
+
28
+
Why This Approach:
29
+
30
+
* Keeps history clean: avoids large, style-only commits.
31
+
* Ensures new contributors are not lost when adapting to project style.
32
+
* Encourages consistency without rigid automation.
33
+
34
+
General Advice: When in doubt, copy the style of the surrounding code.
35
+
The `.clang-format` file is a tool to help you, not a rule to enforce blindly.
36
+
37
+
The utility script `./util/reformat.sh` can also be used to check a few project invariants, such as header guards and include order.
38
+
39
+
== Contributing
40
+
41
+
If you find a bug or have a feature request, please open an issue on the MrDocs GitHub repository: https://github.com/cppalliance/mrdocs/issues
42
+
43
+
If you would like to contribute a feature or bug fix, please open a pull request on the MrDocs GitHub repository: https://github.com/cppalliance/mrdocs/pulls
44
+
45
+
If you would like to discuss a feature or bug fix before opening a pull request, discussing happen in the `#mrdocs` channel on the Cpplang Slack: https://cpplang.slack.com/
0 commit comments