capitalize_dtdocs.py

#!/usr/bin/env python3

# © Aurélien PIERRE - 2022
# Licensed under the terms of the Do What the Fuck You Want to Public License (WTFPL)

import os
import re

"""
Step 1: gather GUI labels and module names from source code,
then create a dictionnary with them 
"""

# Base path to dt source code
# CHANGE ME
PATH = "/home/YOUR_USER/darktable/src"
os.chdir(PATH)

# Base path of the IOP modules
IOP_PATH = os.path.join(PATH, "iop")

# List of module and controls to change
modules = []

# TODO: extend that to libs modules
# Alternatively: just bruteforce our way to all the code, not just src/iop
for iop in os.listdir(os.path.abspath(IOP_PATH)):
    with open(os.path.join(IOP_PATH, iop)) as file:
        content = file.read()
        
        # Find the module name in the IOP method
        # This is an API function that every IOP with a GUI should implement
        regex = r"const char \*name\(\)\s*\{\s*return\s+\_\(\"([a-z ]+)\"\)"
        result = re.search(regex, content)
        
        try:
            modules.append(result.group(1))
        except:
            print("no name in ", iop)
            
        # Find the GUI control names in params introspection
        # Note that this is already used by a Perl script to generate uniform labels as part of introspection
        regex = r"\$DESCRIPTION: \"([a-z 0-9]+)\""
        results = re.finditer(regex, content)
        
        for matchNum, match in enumerate(results, start=1):
            try:
                modules.append(match.group(1))
            except:
                pass
                
"""
Step 2: update Markdown files in dtdocs
For each word in the dictionnary, we find where it is used in Markdown
italics or bold, since dtdocs writing guidelines always reference modules
and controls in italics. Both _italics_ and *italics* syntax are supported.
"""

# Base path to dt doc
# CHANGE ME
PATH = "/home/YOUR_USER/dtdocs"
os.chdir(PATH)

# Base path of the content
CONTENT_PATH = os.path.join(PATH, "content")

# Upper case for the first letter of the regex matches
def capitalize(match):
    return match.group(1) + match.group(2).capitalize() + match.group(3)

for root, directories, files in os.walk(os.path.abspath(CONTENT_PATH)):
    for file in files:
        if file.endswith(".md"):
            content = ""

            # READ
            with open(os.path.join(root, file), "r") as f:
                try:
                    content = f.read()

                    # Find all module's names in current file and capitalize them
                    for module_name in modules:
                        try:
                            # We only detect the names in italics or bold to avoids false positives
                            content = re.sub(rf"([\_\*]+)({re.escape(module_name)})([\_\*]+)", capitalize, content)
                        except:
                            pass
                except:
                    print("[WARNING]", os.path.join(root, file), "not readable")
            
            # WRITE
            with open(os.path.join(root, file), "w") as f:
                if content != "":
                    try:
                        f.write(content)
                        print("[SUCCESS]", os.path.join(root, file), "capitalized")
                    except:
                        print("[ERROR]", os.path.join(root, file), "not writeable")