🔧 overwork style check

doc/mkdocs/docs/api/basic_json/index.md

@@ -292,7 +292,7 @@ Access to the JSON value
 - [**std::hash<basic_json>**](std_hash.md) - return a hash value for a JSON object
 - [**std::swap<basic_json>**](std_swap.md) - exchanges the values of two JSON objects
 
-## Example
+## Examples
 
 ??? example
 

doc/mkdocs/docs/api/json_pointer/index.md

@@ -16,7 +16,13 @@ are the base for JSON patches.
 
 ## Notes
 
-For backwards compatibility `RefStringType` may also be a specialization of [`basic_json`](../basic_json/index.md) in which case `string_t` will be deduced as [`basic_json::string_t`](../basic_json/string_t.md). This feature is deprecated and may be removed in a future major version.
+For backwards compatibility `RefStringType` may also be a specialization of [`basic_json`](../basic_json/index.md) in
+which case `string_t` will be deduced as [`basic_json::string_t`](../basic_json/string_t.md). This feature is deprecated
+and may be removed in a future major version.
+
+## Member types
+
+- [**string_t**](string_t.md) - the string type used for the reference tokens
 
 ## Member functions
 
@@ -31,10 +37,6 @@ For backwards compatibility `RefStringType` may also be a specialization of [`ba
 - [**push_back**](push_back.md) - append an unescaped token at the end of the pointer
 - [**empty**](empty.md) - return whether pointer points to the root document
 
-## Member types
-
-- [**string_t**](string_t.md) - the string type used for the reference tokens
-
 ## See also
 
 - [operator""_json_pointer](../basic_json/operator_literal_json_pointer.md) - user-defined string literal for JSON pointers

doc/mkdocs/scripts/check_structure.py

@@ -2,10 +2,19 @@
 
 import glob
 import os.path
+import re
+
+warnings = 0
+
+
+def report(rule, location, description):
+    global warnings
+    warnings += 1
+    print(f'{warnings:3}. [{rule}] {location}: Error: {description}!')
 
 
 def check_structure():
-    expected_headers = [
+    expected_sections = [
         'Template parameters',
         'Specializations',
         'Iterator invalidation',
@@ -30,7 +39,7 @@ def check_structure():
         'Version history'
     ]
 
-    required_headers = [
+    required_sections = [
         'Examples',
         'Version history'
     ]
@@ -38,8 +47,8 @@ def check_structure():
     files = sorted(glob.glob('api/**/*.md', recursive=True))
     for file in files:
         with open(file) as file_content:
-            header_idx = -1
+            section_idx = -1
-            existing_headers = []
+            existing_sections = []
             in_initial_code_example = False
             previous_line = None
             h1sections = 0
@@ -52,50 +61,55 @@ def check_structure():
 
                 # there should only be one top-level title
                 if h1sections > 1:
-                    print(f'{file}:{lineno+1}: Error: unexpected top-level title "{line}"!')
+                    report('structure/unexpected_section', f'{file}:{lineno+1}', f'unexpected top-level title "{line}"')
                     h1sections = 1
 
                 # Overview pages should have a better title
                 if line == '# Overview':
-                    print(f'{file}:{lineno+1}: Error: overview pages should have a better title!')
+                    report('style/title', f'{file}:{lineno+1}', 'overview pages should have a better title than "Overview"')
 
                 # lines longer than 160 characters are bad (unless they are tables)
                 if len(line) > 160 and '|' not in line:
-                    print(f'{file}:{lineno+1}: Error: line is too long ({len(line)} vs. 160 chars)!')
+                    report('whitespace/line_length', f'{file}:{lineno+1}', f'line is too long ({len(line)} vs. 160 chars)')
 
-                # check if headers are correct
+                # check if sections are correct
                 if line.startswith('## '):
-                    header = line.strip('## ')
+                    current_section = line.strip('## ')
-                    existing_headers.append(header)
+                    existing_sections.append(current_section)
 
-                    if header in expected_headers:
+                    if current_section in expected_sections:
-                        idx = expected_headers.index(header)
+                        idx = expected_sections.index(current_section)
-                        if idx <= header_idx:
+                        if idx <= section_idx:
-                            print(f'{file}:{lineno+1}: Error: header "{header}" is in an unexpected order (should be before "{expected_headers[header_idx]}")!')
+                            report('structure/section_order', f'{file}:{lineno+1}', f'section "{current_section}" is in an unexpected order (should be before "{expected_sections[section_idx]}")')
-                        header_idx = idx
+                        section_idx = idx
                     else:
-                        print(f'{file}:{lineno+1}: Error: header "{header}" is not part of the expected headers!')
+                        report('structure/unknown_section', f'{file}:{lineno+1}', f'section "{current_section}" is not part of the expected sections')
 
                 # code example
-                if line == '```cpp' and header_idx == -1:
+                if line == '```cpp' and section_idx == -1:
                     in_initial_code_example = True
 
                 if in_initial_code_example and line.startswith('//'):
                     if any(map(str.isdigit, line)) and '(' not in line:
-                        print(f'{file}:{lineno+1}: Number should be in parentheses: {line}')
+                        report('style/numbering', f'{file}:{lineno+1}', 'number should be in parentheses: {line}')
 
                 if line == '```' and in_initial_code_example:
                     in_initial_code_example = False
 
                 # consecutive blank lines are bad
                 if line == '' and previous_line == '':
-                    print(f'{file}:{lineno}-{lineno+1}: Error: Consecutive blank lines!')
+                    report('whitespace/blank_lines', f'{file}:{lineno}-{lineno+1}', 'consecutive blank lines')
+
+                # check that admonitions have titles
+                untitled_admonition = re.match(r'^(\?\?\?|!!!) (note|info)$', line)
+                if untitled_admonition:
+                    report('style/admonition_title', f'{file}:{lineno}', f'"{untitled_admonition.group(2)}" admonitions should have a title')
 
                 previous_line = line
 
-            for required_header in required_headers:
+            for required_section in required_sections:
-                if required_header not in existing_headers:
+                if required_section not in existing_sections:
-                    print(f'{file}:{lineno+1}: Error: required header "{required_header}" was not found!')
+                    report('structure/missing_section', f'{file}:{lineno+1}', f'required section "{required_section}" was not found')
 
 
 def check_examples():
@@ -114,9 +128,11 @@ def check_examples():
                 break
 
         if not found:
-            print(f'{example_file}: Error: example file is not used in any documentation file!')
+            report('examples/missing', f'{example_file}', 'example file is not used in any documentation file')
 
 
 if __name__ == '__main__':
+    print(120 * '-')
     check_structure()
     check_examples()
+    print(120 * '-')