Add custom fix-documentation pre-commit-hook

3 files changed, 73 insertions, 0 deletions

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index c840044b9..f7c58420f 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -46,6 +46,12 @@ repos:
         language: system
         types: [python]
         exclude: tests/functional/|tests/input|tests/extensions/data|tests/regrtest_data/|tests/data/|doc/
+    -   id: fix-documentation
+        name: Fix documentation
+        entry: python3 -m script.fix_documentation
+        language: system
+        types: [text]
+        files: ^(ChangeLog|doc/whatsnew/\d+\.\d+\.rst)
 -   repo: https://github.com/pre-commit/mirrors-mypy
     rev: v0.812
     hooks:
diff --git a/script/__init__.py b/script/__init__.py
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/script/__init__.py
diff --git a/script/fix_documentation.py b/script/fix_documentation.py
new file mode 100644
index 000000000..f83327ec3
--- /dev/null
+++ b/script/fix_documentation.py
@@ -0,0 +1,67 @@
+"""Small script to fix various issues with the documentation. Used by pre-commit."""
+# fmt: off
+import argparse
+import re
+import sys
+from typing import List, Union
+
+INVALID_CODE_BLOCK_PATTERN = r"(?<=\s`)([\w\-\.\(\)\=]+\s{0,1}[\w\-\.\(\)\=]*)(?=`[,\.]{0,1}\s|$)"
+
+FILE_CHANGELOG = "ChangeLog"
+CHANGELOG_WHATS_NEW_PREFIX = "What's New in Pylint"
+
+
+def fix_inline_code_blocks(file_content: str) -> str:
+    """Use double quotes for code blocks. RST style.
+
+    Example:
+        `hello-world` -> ``hello-world``
+    """
+    pattern = re.compile(INVALID_CODE_BLOCK_PATTERN)
+    return pattern.sub(r"`\g<0>`", file_content)
+
+
+def changelog_insert_empty_lines(file_content: str) -> str:
+    """Insert up to two empty lines before `What's New` entry in ChangeLog"""
+    lines = file_content.split('\n')
+    version_count = 0
+    for i, line in enumerate(lines):
+        if line.startswith(CHANGELOG_WHATS_NEW_PREFIX):
+            version_count += 1
+            if (
+                version_count == 1 or i < 2
+                or lines[i - 1] == '' and lines[i - 2] == ''
+            ):
+                continue
+            lines.insert(i, '')
+    return '\n'.join(lines)
+
+
+def main(argv: Union[List[str], None] = None) -> int:
+    argv = argv or sys.argv[1:]
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "filenames", nargs="*", metavar="FILES",
+        help="File names to modify",
+    )
+    args = parser.parse_args(argv)
+
+    return_value: int = 0
+    for file_name in args.filenames:
+        with open(file_name) as fp:
+            orignal_content = fp.read()
+        content = orignal_content
+        # Modify files
+        content = fix_inline_code_blocks(content)
+        if file_name == FILE_CHANGELOG:
+            content = changelog_insert_empty_lines(content)
+        # If modified, write changes and eventually return 1
+        if orignal_content != content:
+            with open(file_name, "w") as fp:
+                fp.write(content)
+            return_value |= 1
+    return return_value
+
+
+if __name__ == "__main__":
+    sys.exit(main())