.gitattributes

@@ -1 +1,3 @@
 test-files/**/*.xml binary
+test-files/golden-tests/** text eol=lf
+**.sh text eol=lf

.github/workflows/ci.yml

@@ -612,6 +612,18 @@ jobs:
           cp index.html ../../build/website/index.html
           cp styles.css ../../build/website/styles.css
 
+      - name: Generate Antora UI
+        working-directory: docs/ui
+        run: |
+          # This playbook renders the documentation 
+          # content for the website. It includes
+          # master, develop, and tags.
+          GH_TOKEN="${{ secrets.GITHUB_TOKEN }}"
+          export GH_TOKEN
+          npm ci
+          npx gulp lint
+          npx gulp
+
       - name: Generate Remote Documentation
         working-directory: docs
         run: |

.gitignore

@@ -10,5 +10,8 @@
 /test-files/**/*.bad.xml
 docs/node_modules
 docs/build
+docs/ui/node_modules
+docs/ui/build
+docs/ui/public
 share/mrdocs/libcxx/
 share/mrdocs/clang/

CMakeLists.txt

@@ -399,7 +399,7 @@ if (MRDOCS_BUILD_TESTS)
                 "--stdlib-includes=${LIBCXX_DIR}"
                 "--stdlib-includes=${STDLIB_INCLUDE_DIR}"
                 "--libc-includes=${CMAKE_SOURCE_DIR}/share/mrdocs/headers/libc-stubs"
-                --report=2
+                --log-level=warn
         )
         foreach (action IN ITEMS test create update)
             add_custom_target(
@@ -414,7 +414,7 @@ if (MRDOCS_BUILD_TESTS)
                     "--stdlib-includes=${LIBCXX_DIR}"
                     "--stdlib-includes=${STDLIB_INCLUDE_DIR}"
                     "--libc-includes=${CMAKE_SOURCE_DIR}/share/mrdocs/headers/libc-stubs"
-                    --report=2
+                    --log-level=warn
                 DEPENDS mrdocs-test
             )
         endforeach ()

docs/antora-playbook.yml

@@ -25,7 +25,7 @@ content:
 
 ui:
   bundle:
-    url: 'https://github.com/boostorg/website-v2-docs/releases/download/ui-develop/ui-bundle.zip'
+    url: './ui/build/ui-bundle.zip'
     snapshot: true
 
 antora:

docs/build_docs.sh

@@ -8,6 +8,16 @@
 # Official repository: https://github.com/cppalliance/mrdocs
 #
 
+echo "Building documentation UI"
+cwd=$(pwd)
+script_dir=$(dirname "$(readlink -f "$0")")
+if ! [ -e "$script_dir/ui/build/ui-bundle.zip" ]; then
+  echo "Building antora-ui"
+  cd "$script_dir/ui" || exit
+  ./build.sh
+  cd "$cwd" || exit
+fi
+
 echo "Building documentation with Antora..."
 echo "Installing npm dependencies..."
 npm ci

docs/build_local_docs.sh

@@ -8,6 +8,16 @@
 # Official repository: https://github.com/cppalliance/mrdocs
 #
 
+echo "Building documentation UI"
+cwd=$(pwd)
+script_dir=$(dirname "$(readlink -f "$0")")
+if ! [ -e "$script_dir/ui/build/ui-bundle.zip" ]; then
+  echo "Building antora-ui"
+  cd "$script_dir/ui" || exit
+  ./build.sh
+  cd "$cwd" || exit
+fi
+
 echo "Building documentation with Antora..."
 echo "Installing npm dependencies..."
 npm ci

docs/extensions/config-options-reference.js

@@ -90,6 +90,10 @@ function toDefaultValueStr(value) {
 }
 
 function pushOptionBlocks(options, block, parents = []) {
+    function makeOptionID(option) {
+        return [...parents, option.name].join('_') + "_option"
+    }
+
     block.lines.push('<table class="tableblock frame-all grid-all stretch">')
     block.lines.push('<colgroup>')
     block.lines.push('<col style="width: 23.3333%;">')
@@ -108,7 +112,8 @@ function pushOptionBlocks(options, block, parents = []) {
         let optionName = [...parents, option.name].join('.')
         block.lines.push('<tr>')
         block.lines.push(`<td class="tableblock halign-left valign-top">`)
-        block.lines.push(`<code style="color: darkblue">${optionName}</code>`)
+        const colorStr = option['deprecated'] ? 'red' : 'darkblue'
+        block.lines.push(`<a href="#${makeOptionID(option)}"><code style="color: ${colorStr}">${optionName}</code></a>`)
         block.lines.push(`<br/>`)
         block.lines.push(`<span style="color: darkgreen;">(${toTypeStr(option.type)})</span>`)
         let observations = []
@@ -118,8 +123,11 @@ function pushOptionBlocks(options, block, parents = []) {
         if (option['command-line-only']) {
             observations.push('Command line only')
         }
+        if (option['deprecated']) {
+            observations.push(`Deprecated`)
+        }
         if (observations.length !== 0) {
-            block.lines.push(`<br/><br/>`)
+            block.lines.push(`<br/>`)
             let observationsStr = observations.join(', ')
             block.lines.push(`<span style="color: orangered;">(${observationsStr})</span>`)
         }
@@ -134,14 +142,19 @@ function pushOptionBlocks(options, block, parents = []) {
     // Option details
     for (let option of options) {
         let optionName = [...parents, option.name].join('.')
-        block.lines.push(`<div class="paragraph"><p><b><code style="color: darkblue">${optionName}</code></b></p></div>`)
+        const optionID = optionName.replace(/\./g, '_')
+        const colorStr = option['deprecated'] ? 'red' : 'darkblue'
+        block.lines.push(`<div class="paragraph" id="${makeOptionID(option)}"><p><b><code style="color: ${colorStr}">${optionName}</code></b></p></div>`)
         block.lines.push(`<div class="paragraph"><p><i>${option.brief}</i></p></div>`)
         if (option.details) {
             block.lines.push(`<div class="paragraph"><p>${replaceCodeTags(escapeHtml(option.details))}</p></div>`)
         }
         block.lines.push(`<div class="paragraph"><p>`)
         block.lines.push(`<div class="ulist">`)
         block.lines.push(`<ul>`)
+        if (option['deprecated']) {
+            block.lines.push(`<li><span style="color: red;">Deprecated</span>: ${replaceCodeTags(escapeHtml(option['deprecated']))}</li>`)
+        }
         if (option.type) {
             block.lines.push(`<li>Type: ${toTypeStr(option.type)}</li>`)
         } else {

docs/extensions/mrdocs-releases.js

@@ -163,14 +163,14 @@ module.exports = function (registry) {
 
             // Create table
             let text = '|===\n'
-            text += '|          3+| 🪟 Windows                2+| 🐧 Linux                 \n'
-            text += '| 📃 Release | 📦 7z   | 📦 msi  | 📦 zip  | 📦 tar.xz  | 📦 tar.gz  \n'
+            text += '|          3+| 🪟 Windows                2+| 🐧 Linux               2+| 🍏 macOS                \n'
+            text += '| 📃 Release | 📦 7z   | 📦 msi  | 📦 zip  | 📦 tar.xz  | 📦 tar.gz  | 📦 tar.xz  | 📦 tar.gz  \n'
             releases.sort((a, b) => getReleaseDate(b) - getReleaseDate(a));
             for (const release of releases) {
                 if (release.name === 'llvm-package') continue
                 const date = getReleaseDate(release)
                 text += `| ${release.html_url}[${release.name},window=_blank]\n\n${humanizeDate(date)} `
-                const assetSuffixes = ['win64.7z', 'win64.msi', 'win64.zip', 'Linux.tar.xz', 'Linux.tar.gz']
+                const assetSuffixes = ['win64.7z', 'win64.msi', 'win64.zip', 'Linux.tar.xz', 'Linux.tar.gz', 'Darwin.tar.xz', 'Darwin.tar.gz']
                 for (const suffix of assetSuffixes) {
                     const asset = release.assets.find(asset => asset.name.endsWith(suffix))
                     if (asset) {

docs/modules/ROOT/pages/config-file.adoc

@@ -18,10 +18,15 @@ More information about the generators can be found in the xref:generators.adoc[G
 
 == YAML Schema
 
-To get linting and autocompletion in the config file, a schema for the config can be specified.
-In JetBrains IDEs, `# $schema: <url>` can be used to bind a schema to a file.
-In editors with plugins based on the https://github.com/redhat-developer/yaml-language-server[YAML language server], `# yaml-language-server: $schema=<url>` can be used.
-The schema for `mrdocs.yml` is provided xref:attachment$mrdocs.schema.json[here].
+To get linting and autocompletion in the config file, a schema for the config can be specified. The schema for `mrdocs.yml` is provided xref:attachment$mrdocs.schema.json[here].
+
+The schema for `mrdocs.yml` is available from https://www.schemastore.org/json/, which is automatically detected and used by most editors.
+
+To manually set the schema in an editor, the following can be used:
+
+* In JetBrains IDEs, `# $schema: <url>` can be used to bind a schema to a file.
+* In editors with plugins based on the https://github.com/redhat-developer/yaml-language-server[YAML language server], `# yaml-language-server: $schema=<url>` can be used.
+
 The following shows an example of a file specifying an inline-schema that's compatible with JetBrains IDEs and editors using the YAML language server.
 
 [source,yaml]
@@ -144,13 +149,13 @@ namespace my_library
 
 === Private Symbols
 
-The `implementation-detail` and `see-below` options can be used to designate symbols as implementation details or "see below" in the documentation.
+The `implementation-defined` and `see-below` options can be used to designate symbols as implementation details or "see below" in the documentation.
 
 [,yaml]
 ----
 include-symbols:
   - 'my_library::**'
-implementation-detail:
+implementation-defined:
   - 'my_library::detail::**'
 see-below:
   - 'my_library::see_below::**'

docs/modules/ROOT/pages/generators.adoc

@@ -3,12 +3,12 @@
 MrDocs uses a generator to convert the extracted symbols into documentation.
 MrDocs supports multiple output formats that can be specified via the `generate` option:
 
-The `generate` option can be used to specify the output format:
+The `generator` option can be used to specify the output format:
 
 [source,yaml]
 ----
 # ...
-generate: adoc
+generator: adoc
 # ...
 ----
 

docs/modules/ROOT/pages/usage.adoc

@@ -134,6 +134,15 @@ If you want to use this feature, you need to have CMake installed on your system
 Parameters for cmake, such as `-D BUILDING_TEST=OFF -D MRDOCS_BUILD=ON` can also be specified with the `cmake` option in configuration file.
 MrDocs will always append the `CMAKE_EXPORT_COMPILE_COMMANDS=ON` flag to the cmake command.
 
+[NOTE]
+====
+When the `cmake` option is provided, MrDocs will still adjust the CMake configure arguments to properly generate the compilation database file.
+
+* MrDocs will set the `-S` and `-B` options to the proper directories determined by the `mrdocs.yml` file. If the user explicitly sets `-S` or `-B` in the `cmake` option, these arguments are ignored.
+* If the user explicitly sets the generator with `-G`, the user option will typically be honored. However, if the user explicitly sets the generator to `Visual Studio` or the option is not set and `Visual Studio` is still the default generator, MrDocs will override it to `-G Ninja` to ensure a `compile_commands.json` file is generated.
+* MrDocs will typically ensure the `CMAKE_EXPORT_COMPILE_COMMANDS` flag is set to `ON`. If the user explicitly sets `-D CMAKE_EXPORT_COMPILE_COMMANDS=OFF`, the user flag will be honored. This can be used to manually determine the logic to generate the `compile_commands.json` file in the `CMakeLists.txt` file.
+====
+
 === MrDocs Builds
 
 In many projects, a common pattern is to define a special build configuration for the documentation generation such that:
@@ -224,7 +233,7 @@ And the user can specify that symbols in the `impl` namespace are implementation
 [source,yaml]
 ----
 # ...
-implementation-detail: impl::**
+implementation-defined: impl::**
 # ...
 ----
 

docs/modules/ROOT/partials/mrdocs-example.yml

@@ -1,3 +1,3 @@
 source-root: ../include
 multipage: false
-generate: adoc
+generator: adoc

docs/modules/ROOT/partials/mrdocs-schema-example.yml

@@ -3,4 +3,4 @@
 
 source-root: ../include
 multipage: false
-generate: adoc
+generator: adoc