feat(util): run_all_tests script

Author: alandefreitas

CMakeLists.txt

@@ -29,6 +29,7 @@ option(MRDOCS_INSTALL "Configure install target" ON)
 option(MRDOCS_PACKAGE "Build install package" ON)
 option(MRDOCS_BUILD_SHARED "Link shared" ${BUILD_SHARED_LIBS})
 option(MRDOCS_BUILD_TESTS "Build tests" ${BUILD_TESTING})
+option(MRDOCS_BUILD_STRICT_TESTS "Enable strict tests" ON)
 option(MRDOCS_REQUIRE_GIT "Git is required: not being able to extract version build is an error" ON)
 if (MRDOCS_BUILD_TESTS OR MRDOCS_INSTALL)
     option(MRDOCS_BUILD_DOCS "Build documentation" ON)
@@ -520,10 +521,39 @@ if (MRDOCS_BUILD_TESTS)
         )
     endforeach ()
 
+    #-------------------------------------------------
+    # Self-documentation test (always run; warn-as-error toggled by strict flag)
+    #-------------------------------------------------
+    set(MRDOCS_SELF_DOC_OUTPUT "${CMAKE_BINARY_DIR}/docs/self-reference")
+    set(MRDOCS_SELF_DOC_TAGFILE "${MRDOCS_SELF_DOC_OUTPUT}/reference.tag.xml")
+
+    add_test(NAME mrdocs-self-doc
+        COMMAND
+            mrdocs
+            "${CMAKE_SOURCE_DIR}/CMakeLists.txt"
+                "--config=${CMAKE_SOURCE_DIR}/docs/mrdocs.yml"
+                "--output=${MRDOCS_SELF_DOC_OUTPUT}"
+                --generator=adoc
+                "--addons=${CMAKE_SOURCE_DIR}/share/mrdocs/addons"
+                "--stdlib-includes=${LIBCXX_DIR}"
+                "--stdlib-includes=${STDLIB_INCLUDE_DIR}"
+                "--libc-includes=${CMAKE_SOURCE_DIR}/share/mrdocs/headers/libc-stubs"
+                "--tagfile=${MRDOCS_SELF_DOC_TAGFILE}"
+                --multipage=true
+                --concurrency=16
+                --log-level=debug
+                $<$<BOOL:${MRDOCS_BUILD_STRICT_TESTS}>:--warn-as-error=true>
+        )
+
     #-------------------------------------------------
     # XML lint
     #-------------------------------------------------
-    find_package(LibXml2)
+    if (MRDOCS_BUILD_STRICT_TESTS)
+        # Strict mode expects xml-lint to run; require LibXml2.
+        find_package(LibXml2 REQUIRED)
+    else()
+        find_package(LibXml2)
+    endif()
     if (LibXml2_FOUND)
         find_package(Java REQUIRED Runtime)
         # FindJava
@@ -541,7 +571,16 @@ if (MRDOCS_BUILD_TESTS)
         file(GLOB_RECURSE XML_SOURCES CONFIGURE_DEPENDS test-files/golden-tests/*.xml)
         add_test(NAME xml-lint
                  COMMAND ${LIBXML2_XMLLINT_EXECUTABLE} --dropdtd --noout
-                     --relaxng ${CMAKE_CURRENT_BINARY_DIR}/mrdocs.rng ${XML_SOURCES}
+                 --relaxng ${CMAKE_CURRENT_BINARY_DIR}/mrdocs.rng ${XML_SOURCES}
+                 WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
+    endif()
+
+    #-------------------------------------------------
+    # YAML schema check
+    #-------------------------------------------------
+    if (PYTHON_EXECUTABLE)
+        add_test(NAME yaml-schema-check
+                 COMMAND ${PYTHON_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/util/generate-yaml-schema.py --check
                  WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR})
     endif()
 endif()
@@ -589,7 +628,7 @@ if (MRDOCS_BUILD_DOCS)
         set(DOCS_BUILD_DIR ${DOCS_SOURCE_DIR}/build/site)
         set(DOCS_INSTALL_DIR ${CMAKE_INSTALL_PREFIX}/doc/mrdocs/html)
 
-        # Add custom target for generating documentation
+        # Add a custom target for generating documentation
         add_custom_target(generate_docs
                 ALL
                 COMMAND ${CMAKE_COMMAND} -E echo "Install npm dependencies"

docs/modules/ROOT/pages/contribute.adoc

@@ -3,6 +3,11 @@
 This page contains information for contributors to the Mr.Docs project.
 It is intended to provide an overview of the codebase and the process of adding new features.
 
+Before sending changes, run `python util/run_all_tests.py`.
+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.
+Not every policy can be enforced programmatically, but this script covers the checks that are automated; prefer it over ad-hoc command sequences.
+Use `--skip-docs` to omit docs or `--no-strict` to relax strict warning handling when needed.
+
 == Codebase Overview
 
 The Mr.Docs codebase is divided into several modules:
@@ -49,19 +54,27 @@ As a last step, `DoGenerateAction` converts the public `Config` settings into a
 [#representing_symbols]
 == Representing Symbols
 
-MrDocs has many categories of objects, where we utilize polymorphism with a fixed set of valid derived types, including Symbols (functions, classes, and enums), DocComment blocks, template parameters, template arguments, and data types. For each such family, we follow a consistent file layout. Most of these families are defined in the `mrdocs/Metadata` directory.
+MrDocs has many categories of objects, where we utilize polymorphism with a fixed set of valid derived types, including Symbols (functions, classes, and enums), DocComment blocks, template parameters, template arguments, and data types.
+For each such family, we follow a consistent file layout.
+Most of these families are defined in the `mrdocs/Metadata` directory.
 
-Each base class is defined in its own header and, when necessary, implementation file. Each derived class also has its own header and implementation file. Finally, there is a single aggregator header file that includes all the derived headers. This file centralizes logic that requires knowledge of the full set of variants, such as visitors, comparison operators, and other operations that depend on the discriminator.
+Each base class is defined in its own header and, when necessary, implementation file.
+Each derived class also has its own header and implementation file.
+Finally, there is a single aggregator header file that includes all the derived headers.
+This file centralizes logic that requires knowledge of the full set of variants, such as visitors, comparison operators, and other operations that depend on the discriminator.
 
-Suppose we have a polymorphic family of `Symbol` objects, with derived types `Function`, `Class`, and `Enum`. The files would be organized as follows:
+Suppose we have a polymorphic family of `Symbol` objects, with derived types `Function`, `Class`, and `Enum`.
+The files would be organized as follows:
 
 * The `Symbol/SymbolNodes.inc` file defines the possible derived types and is used to generate code via macros.
 * The `Symbol/SymbolKind.hpp` file defines the `SymbolKind` enum, which is used as a discriminator for the derived types.
 * The base class `Symbol` is defined in `Symbol/BaseSymbol.hpp` and `Symbol/BaseSymbol.cpp` (if needed).
 * The available kinds of derived symbols are defined in `Symbol/<Derived>.hpp` and `Symbol/<Derived>.cpp` files, e.g., `Symbol/Function.hpp` and `Symbol/Function.cpp`.
 * The `Symbol.hpp` file includes all derived headers and defines operations that require knowledge of all variants, such as visitors and comparison operators.
 
-This pattern keeps the individual derived types self-contained while making cross-variant operations explicit and localized. When adding a new derived type, contributors should create its header and source file alongside the existing ones and update the corresponding aggregator file to register the new variant. This keeps the codebase predictable, avoids scattering logic, and ensures that operations over polymorphic families remain easy to find and maintain.
+This pattern keeps the individual derived types self-contained while making cross-variant operations explicit and localized.
+When adding a new derived type, contributors should create its header and source file alongside the existing ones and update the corresponding aggregator file to register the new variant.
+This keeps the codebase predictable, avoids scattering logic, and ensures that operations over polymorphic families remain easy to find and maintain.
 
 [#extract_symbols]
 === Extracting Symbols
@@ -139,8 +152,7 @@ This is necessary to generate the full interface for user-defined types.
 After running the AST traversal on all translation units, `CorpusImpl::build` contains finalization steps for the `Corpus` object.
 At this point, we process C++ constructs that are not directly represented in the AST.
 
-The first finalization step happens in `CorpusImpl::build` (`src/lib/Lib/CorpusImpl.cpp`), where the `Symbol` objects from a single translation unit
-are merged into a map containing the merged results from all other TUs.
+The first finalization step happens in `CorpusImpl::build` (`src/lib/Lib/CorpusImpl.cpp`), where the `Symbol` objects from a single translation unit are merged into a map containing the merged results from all other TUs.
 The merging step is necessary as there may be multiple identical definitions of the same entity.
 For instance, this represents the case where a function is declared at different points in the code base and might have different attributes or comments.
 At this step, the doc comments are also finalized.
@@ -267,7 +279,8 @@ Why This Approach:
 * Ensures new contributors are not lost when adapting to project style.
 * Encourages consistency without rigid automation.
 
-General Advice: When in doubt, copy the style of the surrounding code. The `.clang-format` file is a tool to help you, not a rule to enforce blindly.
+General Advice: When in doubt, copy the style of the surrounding code.
+The `.clang-format` file is a tool to help you, not a rule to enforce blindly.
 
 The utility script `./util/reformat.sh` can also be used to check a few project invariants, such as header guards and include order.
 
@@ -277,4 +290,4 @@ If you find a bug or have a feature request, please open an issue on the MrDocs
 
 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
 
-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/
+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/

util/README.adoc

@@ -1,3 +1,15 @@
 = Build tools
 
 This directory holds additional scripts and files for building and testing.
+
+== Test runner
+
+- Strict tests (self-doc, format check, warn-as-error) are enabled by default; pass `--no-strict` to disable `MRDOCS_BUILD_STRICT_TESTS`.
+- Run `python util/run_all_tests.py` to configure the best release/* preset for your OS, build, and execute the full ctest suite (golden tests first, then the rest).
+- The runner forces compiler warnings to be treated as errors with CI-matching flags: `-Werror -Wall` for gcc/clang and `/WX /W4` for MSVC, without clobbering preset defaults.
+- Add `--update-golden` to refresh golden fixtures before running the test suite when output diffs in error messages are intentional.
+- Use `--preset <name>` to override the automatic selection. The script prefers presets starting with `release/` (or `release-`) that match your OS and compiler, falling back to `debug/*` if needed.
+- After tests (and optional docs), the script installs into `install/<preset>` under the repo root to keep the prefix scoped to the workspace.
+- Docs build runs by default; pass `--skip-docs` to omit the documentation step. Docs are built after install with `MRDOCS_ROOT` pointed at the freshly installed prefix so the generated reference uses that version.
+- Strict tests (self-doc, format check, warn-as-error) are enabled by default; pass `--no-strict` to disable `MRDOCS_BUILD_STRICT_TESTS`.
+- `util/reformat.py` supports `--check` to validate formatting/include guards without modifying files (used by the strict test suite).