180 lines
8.3 KiB
Python
180 lines
8.3 KiB
Python
|
#!/usr/bin/env python
|
||
|
|
|
||
|
|
import glob
|
||
|
|
import os.path
|
||
|
|
import re
|
||
|
|
import sys
|
||
|
|
|
||
|
|
warnings = 0
|
||
|
|
|
||
|
|
|
||
|
|
def report(rule, location, description):
|
||
|
|
global warnings
|
||
|
|
warnings += 1
|
||
|
|
print(f'{warnings:3}. {location}: {description} [{rule}]')
|
||
|
|
|
||
|
|
|
||
|
|
def check_structure():
|
||
|
|
expected_sections = [
|
||
|
|
'Template parameters',
|
||
|
|
'Specializations',
|
||
|
|
'Iterator invalidation',
|
||
|
|
'Requirements',
|
||
|
|
'Member types',
|
||
|
|
'Member functions',
|
||
|
|
'Member variables',
|
||
|
|
'Static functions',
|
||
|
|
'Non-member functions',
|
||
|
|
'Literals',
|
||
|
|
'Helper classes',
|
||
|
|
'Parameters',
|
||
|
|
'Return value',
|
||
|
|
'Exception safety',
|
||
|
|
'Exceptions',
|
||
|
|
'Complexity',
|
||
|
|
'Possible implementation',
|
||
|
|
'Default definition',
|
||
|
|
'Notes',
|
||
|
|
'Examples',
|
||
|
|
'See also',
|
||
|
|
'Version history'
|
||
|
|
]
|
||
|
|
|
||
|
|
required_sections = [
|
||
|
|
'Examples',
|
||
|
|
'Version history'
|
||
|
|
]
|
||
|
|
|
||
|
|
files = sorted(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
|
||
|
|
existing_sections = [] # the list of h2 sections in the file
|
||
|
|
in_initial_code_example = False # whether we are inside the first code example block
|
||
|
|
previous_line = None # the previous read line
|
||
|
|
h1sections = 0 # the number of h1 sections in the file
|
||
|
|
last_overload = 0 # the last seen overload number in the code example
|
||
|
|
documented_overloads = {} # the overloads that have been documented in the current block
|
||
|
|
current_section = None # the name of the current section
|
||
|
|
|
||
|
|
for lineno, original_line in enumerate(file_content.readlines()):
|
||
|
|
line = original_line.strip()
|
||
|
|
|
||
|
|
if line.startswith('# '):
|
||
|
|
h1sections += 1
|
||
|
|
|
||
|
|
# there should only be one top-level title
|
||
|
|
if h1sections > 1:
|
||
|
|
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':
|
||
|
|
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:
|
||
|
|
report('whitespace/line_length', f'{file}:{lineno+1} ({current_section})', f'line is too long ({len(line)} vs. 160 chars)')
|
||
|
|
|
||
|
|
# sections in `<!-- NOLINT -->` comments are treated as present
|
||
|
|
if line.startswith('<!-- NOLINT'):
|
||
|
|
current_section = line.strip('<!-- NOLINT')
|
||
|
|
current_section = current_section.strip(' -->')
|
||
|
|
existing_sections.append(current_section)
|
||
|
|
|
||
|
|
# check if sections are correct
|
||
|
|
if line.startswith('## '):
|
||
|
|
# before starting a new section, check if the previous one documented all overloads
|
||
|
|
if current_section in documented_overloads and last_overload != 0:
|
||
|
|
if len(documented_overloads[current_section]) > 0 and len(documented_overloads[current_section]) != last_overload:
|
||
|
|
expected = list(range(1, last_overload+1))
|
||
|
|
undocumented = [x for x in expected if x not in documented_overloads[current_section]]
|
||
|
|
unexpected = [x for x in documented_overloads[current_section] if x not in expected]
|
||
|
|
if len(undocumented):
|
||
|
|
report('style/numbering', f'{file}:{lineno} ({current_section})', f'undocumented overloads: {", ".join([f"({x})" for x in undocumented])}')
|
||
|
|
if len(unexpected):
|
||
|
|
report('style/numbering', f'{file}:{lineno} ({current_section})', f'unexpected overloads: {", ".join([f"({x})" for x in unexpected])}')
|
||
|
|
|
||
|
|
current_section = line.strip('## ')
|
||
|
|
existing_sections.append(current_section)
|
||
|
|
|
||
|
|
if current_section in expected_sections:
|
||
|
|
idx = expected_sections.index(current_section)
|
||
|
|
if idx <= section_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]}")')
|
||
|
|
section_idx = idx
|
||
|
|
else:
|
||
|
|
if 'index.md' not in file: # index.md files may have a different structure
|
||
|
|
report('structure/unknown_section', f'{file}:{lineno+1}', f'section "{current_section}" is not part of the expected sections')
|
||
|
|
|
||
|
|
# collect the numbered items of the current section to later check if they match the number of overloads
|
||
|
|
if last_overload != 0 and not in_initial_code_example:
|
||
|
|
if len(original_line) and original_line[0].isdigit():
|
||
|
|
number = int(re.findall(r"^(\d+).", original_line)[0])
|
||
|
|
if current_section not in documented_overloads:
|
||
|
|
documented_overloads[current_section] = []
|
||
|
|
documented_overloads[current_section].append(number)
|
||
|
|
|
||
|
|
# code example
|
||
|
|
if line == '```cpp' and section_idx == -1:
|
||
|
|
in_initial_code_example = True
|
||
|
|
|
||
|
|
if in_initial_code_example and line.startswith('//') and line not in ['// since C++20', '// until C++20']:
|
||
|
|
# check numbering of overloads
|
||
|
|
if any(map(str.isdigit, line)):
|
||
|
|
number = int(re.findall(r'\d+', line)[0])
|
||
|
|
if number != last_overload + 1:
|
||
|
|
report('style/numbering', f'{file}:{lineno+1}', f'expected number ({number}) to be ({last_overload +1 })')
|
||
|
|
last_overload = number
|
||
|
|
|
||
|
|
if any(map(str.isdigit, line)) and '(' not in line:
|
||
|
|
report('style/numbering', f'{file}:{lineno+1}', f'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 == '':
|
||
|
|
report('whitespace/blank_lines', f'{file}:{lineno}-{lineno+1} ({current_section})', 'consecutive blank lines')
|
||
|
|
|
||
|
|
# check that non-example admonitions have titles
|
||
|
|
untitled_admonition = re.match(r'^(\?\?\?|!!!) ([^ ]+)$', line)
|
||
|
|
if untitled_admonition and untitled_admonition.group(2) != 'example':
|
||
|
|
report('style/admonition_title', f'{file}:{lineno} ({current_section})', f'"{untitled_admonition.group(2)}" admonitions should have a title')
|
||
|
|
|
||
|
|
previous_line = line
|
||
|
|
|
||
|
|
if 'index.md' not in file: # index.md files may have a different structure
|
||
|
|
for required_section in required_sections:
|
||
|
|
if required_section not in existing_sections:
|
||
|
|
report('structure/missing_section', f'{file}:{lineno+1}', f'required section "{required_section}" was not found')
|
||
|
|
|
||
|
|
|
||
|
|
def check_examples():
|
||
|
|
example_files = sorted(glob.glob('../../examples/*.cpp'))
|
||
|
|
markdown_files = sorted(glob.glob('**/*.md', recursive=True))
|
||
|
|
|
||
|
|
# check if every example file is used in at least one markdown file
|
||
|
|
for example_file in example_files:
|
||
|
|
example_file = os.path.join('examples', os.path.basename(example_file))
|
||
|
|
|
||
|
|
found = False
|
||
|
|
for markdown_file in markdown_files:
|
||
|
|
content = ' '.join(open(markdown_file).readlines())
|
||
|
|
if example_file in content:
|
||
|
|
found = True
|
||
|
|
break
|
||
|
|
|
||
|
|
if not found:
|
||
|
|
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 * '-')
|
||
|
|
|
||
|
|
if warnings > 0:
|
||
|
|
sys.exit(1)
|