From 284d454c3698694cb8b04865ff0f05e4c3ff652d Mon Sep 17 00:00:00 2001
From: Steven Bal <steven@maykinmedia.nl>
Date: Thu, 22 Aug 2024 14:02:42 +0200
Subject: [PATCH 1/2] :construction_worker: [#60] Check if envvars have
 documentation or are excluded from docs

---
 .github/workflows/code_quality.yml | 11 +++++
 bin/check_envvar_usage.py          | 73 ++++++++++++++++++++++++++++++
 2 files changed, 84 insertions(+)
 create mode 100644 bin/check_envvar_usage.py

diff --git a/.github/workflows/code_quality.yml b/.github/workflows/code_quality.yml
index 62da1bf..cdf5d12 100644
--- a/.github/workflows/code_quality.yml
+++ b/.github/workflows/code_quality.yml
@@ -31,3 +31,14 @@ jobs:
       - run: tox
         env:
           TOXENV: ${{ matrix.toxenv }}
+
+  check-envvar-documentation:
+    name: Check if environment variables are documented
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Check environment variables
+        run: python bin/check_envvar_usage.py
diff --git a/bin/check_envvar_usage.py b/bin/check_envvar_usage.py
new file mode 100644
index 0000000..558616f
--- /dev/null
+++ b/bin/check_envvar_usage.py
@@ -0,0 +1,73 @@
+"""
+Script to check if open_api_framework has properly documented (or excluded) all environment
+variables that are loaded by the library itself
+"""
+
+import ast
+import sys
+from pathlib import Path
+
+
+class ConfigChecker(ast.NodeVisitor):
+    def __init__(self):
+        self.issues = []
+
+    def visit_Call(self, node):
+        if isinstance(node.func, ast.Name) and node.func.id == "config":
+            has_help_text = False
+            has_add_to_docs = False
+
+            # Check for 'help_text' or 'add_to_docs' in the arguments
+            for keyword in node.keywords:
+                if keyword.arg == "help_text" and isinstance(
+                    keyword.value, (ast.Constant, ast.JoinedStr)
+                ):
+                    has_help_text = True
+                elif (
+                    keyword.arg == "add_to_docs"
+                    and isinstance(keyword.value, ast.Constant)
+                    and keyword.value.value is False
+                ):
+                    has_add_to_docs = True
+
+            # Record issue if neither is found
+            if not (has_help_text or has_add_to_docs):
+                self.issues.append((node.lineno, node.col_offset))
+
+        self.generic_visit(node)
+
+
+def check_config_usage(file_path):
+    with file_path.open("r") as source:
+        tree = ast.parse(source.read(), filename=str(file_path))
+
+    checker = ConfigChecker()
+    checker.visit(tree)
+
+    return checker.issues
+
+
+def check_library(directory):
+    issues = {}
+    for file_path in directory.rglob("*.py"):
+        issues_in_file = check_config_usage(file_path)
+        if issues_in_file:
+            issues[file_path] = issues_in_file
+
+    return issues
+
+
+# Example usage
+library_directory = Path("open_api_framework/")
+issues = check_library(library_directory)
+
+if issues:
+    for file_path, positions in issues.items():
+        for lineno, col_offset in positions:
+            print(
+                f"Issue in {file_path} at line {lineno}, column {col_offset}: "
+                "'config' call lacks 'help_text' or 'add_to_docs=False'"
+            )
+    sys.exit(1)
+else:
+    print("All 'config' calls are correctly documented.")

From 2efd209b53e00bc2cc3490eea08313dc37924ba2 Mon Sep 17 00:00:00 2001
From: Steven Bal <steven@maykinmedia.nl>
Date: Fri, 23 Aug 2024 11:01:39 +0200
Subject: [PATCH 2/2] :wrench: Add missing envvar help texts

---
 open_api_framework/conf/base.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/open_api_framework/conf/base.py b/open_api_framework/conf/base.py
index dae8884..8a507a1 100644
--- a/open_api_framework/conf/base.py
+++ b/open_api_framework/conf/base.py
@@ -849,7 +849,7 @@ def init_sentry(before_send: Callable | None = None):
 ELASTIC_APM_SERVER_URL = config(
     "ELASTIC_APM_SERVER_URL",
     None,
-    "URL where Elastic APM is hosted",
+    help_text="URL where Elastic APM is hosted",
     group="Elastic APM",
 )
 ELASTIC_APM = {
@@ -867,7 +867,7 @@ def init_sentry(before_send: Callable | None = None):
     "SECRET_TOKEN": config(
         "ELASTIC_APM_SECRET_TOKEN",
         "default",
-        "Token used to communicate with Elastic APM",
+        help_text="Token used to communicate with Elastic APM",
         group="Elastic APM",
     ),
     "SERVER_URL": ELASTIC_APM_SERVER_URL,