Track number of Sphinx build warnings

Author: m-aciek

.github/workflows/update.yml

@@ -19,7 +19,7 @@ jobs:
       - uses: actions/checkout@v4
       - run: sudo apt-get install -y gettext
       - run: uv run generate.py  # generates "index.html"
-      - run: mkdir -p build && cp index.html style.css build
+      - run: mkdir -p build && cp index.html style.css warnings* build
       - name: Deploy 🚀
         if: github.event_name != 'pull_request'
         uses: JamesIves/github-pages-deploy-action@v4

build_warnings.py

@@ -0,0 +1,29 @@
+from pathlib import Path
+from shutil import copyfile
+
+import sphinx.cmd.build
+
+
+def number(clones_dir: str, repo: str, language_code: str) -> int:
+    Path(clones_dir, f'cpython/Doc/locales/{language_code}').mkdir(parents=True)
+    Path(clones_dir, f'cpython/Doc/locales/{language_code}/LC_MESSAGES').symlink_to(
+        Path(clones_dir, repo), True
+    )
+    sphinx.cmd.build.main(
+        (
+            '--builder',
+            'html',
+            '--fresh-env',
+            '--jobs',
+            'auto',
+            '--define',
+            f'language={language_code}',
+            '--verbose',
+            '--warning-file',
+            warning_file := f'{clones_dir}/warnings-{language_code}.txt',
+            f'{clones_dir}/cpython/Doc',  # sourcedir
+            './build',  # outputdir
+        )
+    )
+    copyfile(warning_file, f'warnings-{language_code}.txt')
+    return len(Path(warning_file).read_text().splitlines())

generate.py

@@ -6,6 +6,8 @@
 #     "jinja2",
 #     "requests",
 #     "docutils",
+#     "sphinx",
+#     "python-docs-theme",
 # ]
 # ///
 import subprocess
@@ -19,11 +21,12 @@
 from git import Repo
 from jinja2 import Template
 
-import contribute
+import build_warnings
 import build_status
+import contribute
 from visitors import get_number_of_visitors
 from completion import branches_from_devguide, get_completion, TranslatorsData
-from repositories import get_languages_and_repos, Language
+from repositories import Language, get_languages_and_repos
 
 generation_time = datetime.now(timezone.utc)
 
@@ -50,16 +53,19 @@ def get_completion_progress() -> Iterator['LanguageProjectData']:
             if repo:
                 completion, translators_data = get_completion(clones_dir, repo)
                 visitors_num = get_number_of_visitors(language.code) if built else 0
+                issues = build_warnings.number(clones_dir, repo, language.code)
             else:
                 completion = 0.0
                 translators_data = TranslatorsData(0, False)
                 visitors_num = 0
+                issues = 0
             yield LanguageProjectData(
                 language,
                 repo,
                 completion,
                 translators_data,
                 visitors_num,
+                issues,
                 built,
                 in_switcher=languages_built.get(language.code),
                 uses_platform=language.code in contribute.pulling_from_transifex,
@@ -74,6 +80,7 @@ class LanguageProjectData:
     completion: float
     translators: TranslatorsData
     visitors: int
+    issues: int
     built: bool
     in_switcher: bool | None
     uses_platform: bool

style.css

@@ -39,7 +39,7 @@ th {
 .progress-bar.low + .progress-bar-outer-label {
   display: inline-block;
 }
-td[data-label="visitors"], td[data-label="translators"] {
+td[data-label="visitors"], td[data-label="translators"], td[data-label="issues"] {
   text-align: right;
 }
 td[data-label="completion"] {

template.html.jinja

@@ -12,8 +12,9 @@
   <th>language</th>
   <th>contribute</th>
   <th>build</th>
-  <th>visitors*</th>
+  <th>visitors¹</th>
   <th>translators</th>
+  <th>warnings²</th>
   <th>completion</th>
 </tr>
 </thead>
@@ -47,6 +48,7 @@
     {{ project.translators.number }}
     {% if project.translators.link %}</a>{% endif %}
   </td>
+    <td data-label="issues"><a href="warnings-{{ project.language.code }}.txt" target="_blank">{{ project.issues }}</a></td>
   <td data-label="completion">
     <div class="progress-bar" style="width: {{ project.completion }}%;">{{ "{:.2f}".format(project.completion) }}%</div>
     <div class="progress-bar-outer-label">{{ "{:.2f}".format(project.completion) }}%</div>
@@ -55,7 +57,8 @@
 {% endfor %}
 </tbody>
 </table>
-<p>* sum of <a href="https://plausible.io/data-policy#how-we-count-unique-users-without-cookies" target="_blank">daily unique visitors</a> since 8 June 2024</p>
+<p>¹ sum of <a href="https://plausible.io/data-policy#how-we-count-unique-users-without-cookies" target="_blank">daily unique visitors</a> since 8 June 2024</p>
+<p>² number of Sphinx build process warnings</p>
 <p>For more information about translations, see the <a href="https://devguide.python.org/documentation/translating/" target="_blank">Python Developer’s Guide</a>.</p>
 <p>Last updated at {{ generation_time.strftime('%A, %-d %B %Y, %-H:%M:%S %Z') }} (in {{ duration // 60 }}:{{ "{:02}".format(duration % 60) }} minutes).</p>
 </body>