feat: quick reference index page

fix #242

fix #575

Author: alandefreitas

docs/mrdocs.schema.json

@@ -231,6 +231,16 @@
       ],
       "title": "Generator used to create the documentation"
     },
+    "global-namespace-index": {
+      "default": true,
+      "description": "When set to true, the page for the global namespace will recursively list all symbols in the documentation, not just those in the global namespace. This makes the global namespace page act as an index for the entire project.",
+      "enum": [
+        true,
+        false
+      ],
+      "title": "Use the global namespace page as an index for all symbols",
+      "type": "boolean"
+    },
     "ignore-failures": {
       "default": false,
       "description": "When set to true, MrDocs continues to generate the documentation even if there are AST visitation failures. AST visitation failures occur when the source code contains constructs that are not supported by MrDocs.",

share/mrdocs/addons/generator/adoc/partials/symbol.adoc.hbs

@@ -219,4 +219,13 @@
 {{#each symbol.doc.sees}}
 {{>javadoc/see .}}
 {{/each}}
+{{/if}}
+{{! Recursive index for multipage global namespace }}
+{{#if (and (eq symbol.kind "namespace") @root.config.multipage @root.config.global-namespace-index (eq @root.symbol.kind "namespace") (not @root.symbol.name) (not @root.symbol.parent)) }}
+{{#each symbol.members.namespaces}}
+{{#if isRegular}}
+{{#> markup/dynamic-level-h id=null }}{{> symbol/qualified-name . }} namespace{{/markup/dynamic-level-h}}
+{{> symbol symbol=. id=null traversing-global-namespace=true }}
+{{/if}}
+{{/each}}
 {{/if}}

share/mrdocs/addons/generator/common/partials/symbol/members-table.hbs

@@ -16,7 +16,7 @@
 --}}
 {{#if members}}
 {{#if (or (eq members[0].class "name") (any_of_by members "isRegular" "isSeeBelow"))}}
-{{#>markup/h level=(select @root.config.multipage 1 2)}}{{title}}{{/markup/h}}
+{{#>markup/h level=(select @root.config.multipage (select traversing-global-namespace 2 1) 2)}}{{title}}{{/markup/h}}
 {{>symbol/detail/members-table-impl members=members isName=(eq members[0].class "name") includeBrief=(select (any_of_by members "doc") true false) title=title}}
 
 {{/if}}

share/mrdocs/addons/generator/html/partials/symbol.html.hbs

@@ -313,6 +313,15 @@
 {{/each}}
 </div>
 {{/if}}
+{{! Recursive index for multipage global namespace }}
+{{#if (and (eq symbol.kind "namespace") @root.config.multipage @root.config.global-namespace-index (eq @root.symbol.kind "namespace") (not @root.symbol.name) (not @root.symbol.parent)) }}
+{{#each symbol.members.namespaces}}
+{{#if isRegular}}
+{{#> markup/dynamic-level-h id=null }}{{> symbol/qualified-name . }} namespace{{/markup/dynamic-level-h}}
+{{> symbol symbol=. id=null traversing-global-namespace=true }}
+{{/if}}
+{{/each}}
+{{/if}}
 {{#unless @root.config.multipage }}
 </div>
 {{/unless}}

src/lib/ConfigOptions.json

@@ -409,6 +409,13 @@
         "details": "When set to true, MrDocs creates a page for each namespace in the documentation.",
         "type": "bool",
         "default": true
+      },
+      {
+        "name": "global-namespace-index",
+        "brief": "Use the global namespace page as an index for all symbols",
+        "details": "When set to true, the page for the global namespace will recursively list all symbols in the documentation, not just those in the global namespace. This makes the global namespace page act as an index for the entire project.",
+        "type": "bool",
+        "default": true
       }
     ]
   },