Merge 60ea4e8f8b into 0457de21cf

.gitignore

@@ -32,6 +32,7 @@
 /docs/mkdocs/docs/__pycache__/
 /docs/mkdocs/docs/examples/
 /docs/mkdocs/docs/images/json.gif
+/docs/mkdocs/scripts/__pycache__/
 /docs/mkdocs/site/
 /docs/mkdocs/venv/
 

docs/mkdocs/docs/api/internal/index.md

@@ -0,0 +1,9 @@
+---
+x-nlohmann-json-is-internal: true
+---
+
+# Developer Documentation
+
+!!! missing
+
+    This section is under construction.

docs/mkdocs/mkdocs.yml

@@ -293,6 +293,8 @@ nav:
         - 'NLOHMANN_JSON_VERSION_MAJOR': api/macros/nlohmann_json_version_major.md
         - 'NLOHMANN_JSON_VERSION_MINOR': api/macros/nlohmann_json_version_major.md
         - 'NLOHMANN_JSON_VERSION_PATCH': api/macros/nlohmann_json_version_major.md
+      - Internal:
+        - api/internal/index.md
 
 # Extras
 extra:
@@ -358,6 +360,9 @@ plugins:
             'api/basic_json/operator_literal_json.md': api/operator_literal_json.md
             'api/basic_json/operator_literal_json_pointer.md': api/operator_literal_json_pointer.md
             'api/json_pointer/operator_string.md': api/json_pointer/operator_string_t.md
+    - mkdocs-simple-hooks:
+        hooks:
+          on_page_context: scripts.internal_section:on_page_context
 
 extra_css:
     - css/custom.css

docs/mkdocs/scripts/check_structure.py

@@ -1,4 +1,4 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 import glob
 import os.path
@@ -8,6 +8,28 @@ import sys
 warnings = 0
 
 
+def filter_internal(files):
+    try:
+        import mkdocs.utils.meta
+    except ModuleNotFoundError:
+        print('Module mkdocs.utils.meta not found. Cannot exclude internal documentation pages from checks.')
+        return files
+
+    internal_paths = []
+    for file in files:
+        _, data = mkdocs.utils.meta.get_data(file)
+        if data.get('x-nlohmann-json-is-internal', False):
+            internal_paths.append(os.path.dirname(file))
+
+    def parent_of(path, parent):
+        return os.path.commonpath([parent]) == os.path.commonpath([path, parent])
+
+    return [
+        file for file in files
+        if not any(parent_of(file, path) for path in internal_paths)
+    ]
+
+
 def report(rule, location, description):
     global warnings
     warnings += 1
@@ -45,7 +67,7 @@ def check_structure():
         'Version history'
     ]
 
-    files = sorted(glob.glob('api/**/*.md', recursive=True))
+    files = sorted(filter_internal(glob.glob('api/**/*.md', recursive=True)))
     for file in files:
         with open(file) as file_content:
             section_idx = -1                 # the index of the current h2 section

docs/mkdocs/scripts/internal_section.py

@@ -0,0 +1,30 @@
+import sys
+
+from copy import deepcopy
+from mkdocs.structure.nav import Navigation, Section, Page
+
+def _get_internal_sections(items, current_page):
+    res = []
+    sections = [item for item in items if isinstance(item, Section)]
+    while sections:
+        for section in sections[:]:
+            for item in section.children:
+                if isinstance(item, Section):
+                    sections.append(item)
+                elif isinstance(item, Page):
+                    if item.meta.get("x-nlohmann-json-is-internal", False):
+                        res.append(section)
+            sections.remove(section)
+    return res
+
+def on_page_context(context, page, config, nav):
+    sys.setrecursionlimit(1200)
+    nav = deepcopy(nav)
+    context["nav"] = nav
+
+    sections = _get_internal_sections(nav.items, page)
+    for section in sections:
+        if not section.active:
+            section.children = [child for child in section.children if child.is_index]
+
+    return context