support doxygen-like filters

#feat

#fix 761

#fix 751

Author: alandefreitas

.github/workflows/ci.yml

@@ -640,6 +640,8 @@ jobs:
             "html"
           )
           
+          cp example/external/url/mrdocs.yml boost/libs/url/doc/mrdocs.yml
+          
           # Generate the demos for each variant and generator
           for variant in single multi; do
             for generator in "${generators[@]}"; do

docs/mrdocs.schema.json

@@ -8,14 +8,10 @@
       "type": "string"
     },
     "anonymous-namespaces": {
-      "default": "always",
+      "default": true,
       "description": "Determine whether symbols in anonymous namespaces should be extracted. When set to `always`, symbols in anonymous namespaces are always extracted. When set to `dependency`, symbols in anonymous namespaces are extracted only if they are referenced by the source code. When set to `never`, symbols in anonymous namespaces are never extracted.",
-      "enum": [
-        "always",
-        "dependency",
-        "never"
-      ],
-      "title": "Extraction policy for anonymous namespaces"
+      "title": "Extraction policy for anonymous namespaces",
+      "type": "boolean"
     },
     "base-url": {
       "default": "",
@@ -44,52 +40,62 @@
       "title": "Additional defines passed to the compiler",
       "type": "array"
     },
-    "detect-sfinae": {
-      "default": true,
-      "description": "When set to true, MrDocs detects SFINAE expressions in the source code and extracts them as part of the documentation. Expressions such as `std::enable_if<...>` are detected, removed, and documented as a requirement.",
-      "title": "Detect SFINAE expressions",
-      "type": "boolean"
-    },
     "embedded": {
       "default": false,
-      "title": "Output an embeddable document, which excludes the header, the footer, and everything outside the body of the document. This option is useful for producing documents that can be inserted into an external template.",
+      "description": "Output an embeddable document, which excludes the header, the footer, and everything outside the body of the document. This option is useful for producing documents that can be inserted into an external template.",
+      "title": "Output an embeddable document",
       "type": "boolean"
     },
-    "filters": {
-      "properties": {
-        "symbols": {
-          "description": "Symbol filters. Symbols that match these filters are extracted. The filters are applied to the fully qualified name of the symbol.",
-          "properties": {
-            "exclude": {
-              "default": [],
-              "description": "Specifies symbol exclusion patterns. Symbols that match these patterns are not extracted. The patterns are applied to the fully qualified name of the symbol.",
-              "items": {
-                "type": "string"
-              },
-              "title": "Specifies symbol exclusion patterns",
-              "type": "array"
-            },
-            "include": {
-              "default": [],
-              "description": "Specifies symbol inclusion patterns. Symbols that match these patterns are extracted. The patterns are applied to the fully qualified name of the symbol.",
-              "items": {
-                "type": "string"
-              },
-              "title": "Specifies symbol inclusion patterns",
-              "type": "array"
-            }
-          },
-          "required": [],
-          "title": "Symbol filters",
-          "type": "object"
-        }
+    "exclude": {
+      "default": [],
+      "description": "Symbols defined in files in these directories are not extracted even if they are in the list of include directories. When relative, the paths are relative to the directory of the mrdocs configuration file. For instance, \"include/experimental\" will exclude all files in the directory `<config-dir>/include/experimental`.",
+      "items": {
+        "type": "string"
+      },
+      "title": "Input directories to exclude",
+      "type": "array"
+    },
+    "exclude-patterns": {
+      "default": [],
+      "description": "File patterns to exclude. Files that match these patterns are not extracted even if they are in the list of include directories. The patterns are relative to the configuration file. A single * will match all files in the directory. Double ** will match all files in the directory and its subdirectories.",
+      "items": {
+        "type": "string"
+      },
+      "title": "File patterns to exclude",
+      "type": "array"
+    },
+    "exclude-symbols": {
+      "default": [],
+      "description": "A symbol that matches one of these patterns is not extracted even if whitelisted by \"include-symbols\". See the documentation for \"include-symbols\" for the pattern syntax.",
+      "items": {
+        "type": "string"
+      },
+      "title": "Symbol patterns to exclude",
+      "type": "array"
+    },
+    "file-patterns": {
+      "default": [
+        "*.hpp",
+        "*.h",
+        "*.hh",
+        "*.ipp",
+        "*.inc",
+        "*.cpp",
+        "*.cc",
+        "*.cxx",
+        "*.c",
+        "*.hxx"
+      ],
+      "description": "File patterns to include. Only the files that match these patterns are extracted. The patterns are relative to the input directories.",
+      "items": {
+        "type": "string"
       },
-      "required": [],
-      "title": "Filters",
-      "type": "object"
+      "title": "File patterns to include",
+      "type": "array"
     },
-    "generate": {
+    "generator": {
       "default": "adoc",
+      "description": "The generator is responsible for creating the documentation from the extracted symbols. The generator uses the extracted symbols and the templates to create the documentation. The generator can create different types of documentation such as HTML, XML, and AsciiDoc.",
       "enum": [
         "adoc",
         "html",
@@ -111,32 +117,21 @@
     },
     "implementation-defined": {
       "default": [],
-      "description": "Namespaces for symbols rendered as \"implementation-defined\". Symbols in these are rendered as \"implementation-defined\" in the documentation. This option is used to exclude symbols from the documentation that are considered part of the private API of the project. An \"implementation-defined\" symbol has no documentation page in the output. If any other symbol refers to it, the reference is rendered as \"implementation-defined\".",
+      "description": "Symbols that match one of these filters are tagged as \"implementation-defined\" in the documentation, and so do symbols in scopes tagged as \"implementation-defined\". This option is used to exclude symbols from the documentation that are considered part of the private API of the project. An \"implementation-defined\" symbol has no documentation page in the output. If any other symbol refers to it, the reference is rendered as \"implementation-defined\". See the documentation for \"include-symbol\" for the pattern syntax.",
       "items": {
         "type": "string"
       },
-      "title": "Namespaces for symbols rendered as \"implementation-defined\"",
+      "title": "Symbols rendered as \"implementation-defined\"",
       "type": "array"
     },
-    "inaccessible-bases": {
-      "default": "always",
-      "description": "Determine whether inaccessible base classes should be extracted. When set to `always`, inaccessible base classes are always extracted. When set to `dependency`, inaccessible base classes are extracted only if they are referenced by the source code. When set to `never`, inaccessible base classes are never extracted.",
-      "enum": [
-        "always",
-        "dependency",
-        "never"
-      ],
-      "title": "Extraction policy for inaccessible base classes"
-    },
-    "inaccessible-members": {
-      "default": "always",
-      "description": "Determine whether inaccessible members, such as private members of records, should be extracted. When set to `always`, inaccessible members are always extracted. When set to `dependency`, inaccessible members are extracted only if they are referenced by the source code. When set to `never`, inaccessible members are never extracted.",
-      "enum": [
-        "always",
-        "dependency",
-        "never"
-      ],
-      "title": "Extraction policy for inaccessible members"
+    "include-symbols": {
+      "default": [],
+      "description": "If any patterns are defined here, only symbols that match one of these patterns are extracted. The patterns are applied to the fully qualified name of the symbol without any leading \"::\". A single \"*\" will match all symbols in the namespace. Double \"**\" will match all symbols in the namespace and its subnamespaces. The patterns also support \"?\" for any chars, \"[<chars>]\" for charsets, \"[^<chars>]\" for inverted charsets, and \"{<glob>,...}\" for alternatives.",
+      "items": {
+        "type": "string"
+      },
+      "title": "Symbol patterns to include",
+      "type": "array"
     },
     "includes": {
       "default": [],
@@ -148,30 +143,15 @@
       "type": "array"
     },
     "input": {
-      "description": "Include files to extract. Only the files listed in this option are extracted. The paths are relative to the mrdocs configuration file.",
-      "properties": {
-        "file-patterns": {
-          "default": [],
-          "description": "File patterns to include. Only the files that match these patterns are extracted. The patterns are relative to the input directories.",
-          "items": {
-            "type": "string"
-          },
-          "title": "File patterns to include",
-          "type": "array"
-        },
-        "include": {
-          "default": [],
-          "description": "Input directories to include. Only the files in these directories are extracted. The paths are relative to the mrdocs configuration file.",
-          "items": {
-            "type": "string"
-          },
-          "title": "Input directories to include",
-          "type": "array"
-        }
+      "default": [
+        "<source-root>/."
+      ],
+      "description": "Input directories to extract. Only symbols defined in files in these directories are extracted. The paths are relative to the mrdocs configuration file.",
+      "items": {
+        "type": "string"
       },
-      "required": [],
-      "title": "Include files to extract",
-      "type": "object"
+      "title": "Input directories to extract symbols from",
+      "type": "array"
     },
     "legible-names": {
       "default": true,
@@ -202,15 +182,23 @@
       "title": "Directory or file for generating output",
       "type": "string"
     },
-    "referenced-declarations": {
-      "default": "never",
-      "description": "Determine whether external declarations should be extracted when they are referenced in the source code. If this option is not `never`, a second pass happens in the extraction process to extract dependencies in the Corpus. When set to `always`, external declarations are always extracted. When set to `dependency`, external declarations are extracted only if they are referenced by the source code. When set to `never`, external declarations are never extracted.",
-      "enum": [
-        "always",
-        "dependency",
-        "never"
-      ],
-      "title": "Extraction policy for references to external declarations"
+    "private-bases": {
+      "default": true,
+      "description": "Determine whether private base classes should be extracted",
+      "title": "Extraction policy for private base classes",
+      "type": "boolean"
+    },
+    "private-members": {
+      "default": false,
+      "description": "Determine whether private class members should be extracted",
+      "title": "Extraction policy for private class members",
+      "type": "boolean"
+    },
+    "recursive": {
+      "default": true,
+      "description": "Recursively include files. When set to true, MrDocs includes files in subdirectories of the input directories. When set to false, MrDocs includes only the files in the input directories.",
+      "title": "Recursively include files from \"input\" paths",
+      "type": "boolean"
     },
     "report": {
       "default": 1,
@@ -222,15 +210,22 @@
     },
     "see-below": {
       "default": [],
-      "description": "Namespaces for symbols rendered as \"see-below\". Symbols in these namespaces are rendered as \"see-below\" in the documentation. This option is used to exclude details about symbols from the documentation that are considered part of the private API of the project. In the documentation page for this symbol, the synopsis of the implementation of a \"see-below\" symbol is rendered as \"see-below\". When the symbol is a scope (such as a namespace or record), its members are not listed. The rest of the documentation is rendered as usual.",
+      "description": "Symbols that match one of these filters are tagged as \"see-below\" in the documentation, and so do symbols in scopes tagged as \"see-below\". This option is used to remove details about symbols that are considered part of the private API of the project. In the documentation page for this symbol, the synopsis of the implementation is rendered as \"see-below\" and members of scopes (such as a namespace or record) are not listed. The rest of the documentation is rendered as usual. See the documentation for \"include-symbol\" for the pattern syntax.",
       "items": {
         "type": "string"
       },
-      "title": "Namespaces for symbols rendered as \"see-below\"",
+      "title": "Symbols rendered as \"see-below\"",
       "type": "array"
     },
+    "sfinae": {
+      "default": true,
+      "description": "When set to true, MrDocs detects SFINAE expressions in the source code and extracts them as part of the documentation. Expressions such as `std::enable_if<...>` are detected, removed, and documented as a requirement.",
+      "title": "Detect and reduce SFINAE expressions",
+      "type": "boolean"
+    },
     "source-root": {
       "default": "<config-dir>",
+      "description": "Path to the root directory of the source code. This path is used as a default for input files and a base for relative paths formed from absolute paths.",
       "title": "Path to the root directory of the source code",
       "type": "string"
     },

docs/mrdocs.yml

@@ -3,5 +3,13 @@
 
 verbose: true
 source-root: ..
+input:
+  - ../include
+file-patterns:
+  - '*.hpp'
+include-symbols:
+  - 'clang::mrdocs::**'
+implementation-defined:
+  - 'clang::mrdocs::detail'
 multipage: false
-generate: adoc
+generator: adoc

docs/website/render.js

@@ -74,7 +74,7 @@ target_compile_features(${sourceBasename} PRIVATE cxx_std_23)
         mrdocsInput,
         `--output=${mrdocsOutput}`,
         '--multipage=true',
-        '--generate=html',
+        '--generator=html',
         '--embedded=true',
     ];
     const command = args.join(' ');

docs/website/snippets/mrdocs.yml

@@ -1,4 +1,3 @@
 source-root: .
 input:
-  include:
-    - .
+  - .

example/external/url/mrdocs.yml

@@ -0,0 +1,65 @@
+# Input
+source-root: ..
+# Directories that contain documented source files
+input:
+  - ../include
+# Patterns to filter out the source-files in the directories
+file-patterns:
+  - '*.hpp'
+
+# Filters
+include-symbols:
+  - 'boost::urls::**'
+exclude-symbols:
+  # Exclude implementation details
+  - 'boost::urls::detail'
+  - 'boost::urls::*::detail'
+  # Exclude implementation details defined elsewhere
+  - 'boost::urls::*_unsafe'
+  - 'boost::urls::*_t'
+  - 'boost::urls::make_error_code'
+  - 'boost::urls::make_void'
+implementation-defined:
+  - 'boost::urls::implementation_defined'
+  - 'boost::urls::grammar::implementation_defined'
+  - 'boost::urls::string_token::implementation_defined'
+  - 'boost::urls::grammar::*_t'
+  - 'boost::urls::grammar::make_error_*'
+  - 'boost::urls::grammar::operator_*'
+  - 'boost::urls::string_token::*_t'
+see-below:
+  - 'boost::urls::see_below'
+  - 'boost::urls::grammar::see_below'
+  - 'boost::urls::string_token::see_below'
+
+# Generator
+generate: adoc
+base-url: https://www.github.com/boostorg/url/blob/develop/include/ # boost/url/url_view.hpp
+
+# Style
+verbose: true
+multipage: true
+
+# The target for MrDocs simply includes all symbols defined in all
+# headers with the appropriate compilation options.
+# Nothing else should be included in the MrDocs configuration or 
+# would be useful to MrDocs.
+#
+# This single source file not only includes all symbols (the source
+# files do not collectively include all headers) but also makes MrDocs
+# run much faster than relying on the entire library.
+#
+# The time to extract the declarations went from ~8m6s to ~3s in our
+# experiments: a 162x speedup while including all symbols!
+#
+# In practice, this special target is simply emulating the
+# default behavior of the standardese tool with MrDocs, which
+# requires the user to clearly specify the targets via the
+# compilation database.
+#
+# The BOOST_URL_MRDOCS_BUILD=ON is the only option we usually need
+# here.
+# The other options are set just to ensure other targets are
+# ignored even if these options are set as ON in the cache.
+#
+cmake: '-D BOOST_URL_MRDOCS_BUILD=ON -D CMAKE_CXX_STANDARD=20 -D BOOST_URL_BUILD_FUZZERS=OFF -D BOOST_URL_BUILD_EXAMPLES=OFF -D BOOST_URL_BUILD_TESTS=OFF -D BUILD_TESTING=OFF'

include/mrdocs/Config.hpp

@@ -120,7 +120,8 @@ class MRDOCS_DECL
             This string will always be native style
             and have a trailing directory separator.
         */
-        std::string configDir;
+        std::string
+        configDir() const;
 
         /** Full path to the mrdocs root directory
 

include/mrdocs/Config/ReferenceDirectories.hpp

@@ -18,9 +18,15 @@ namespace clang {
 namespace mrdocs {
 
 /** Reference directories used to resolve paths
+
+    These are the main reference directories used to resolve paths in the
+    application.
+
+    All other reference directories come directly from the
+    configuration file.
  */
-struct ReferenceDirectories {
-    std::string configDir;
+struct ReferenceDirectories
+{
     std::string cwd;
     std::string mrdocsRoot;
 };