build: Github action to automate documentation generation after new release

Author: cezary.maszczyk

.github/workflows/build_docs_on_new_release.yml

@@ -4,30 +4,39 @@ on:
   release:
     types: [published]
 
+permissions:
+  contents: write
+
 jobs:
   release-build:
     runs-on: ubuntu-latest
 
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.PAT }}
 
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
           python-version: "3.12"
 
-      - name: Build documentation
+      - name: Download test resources
+        run: |
+          pip install requests
+          python ./tests/resources.py download
+
+      - name: Build documentation and update badges
         run: |
           python -m pip install --upgrade pip
           pip install -r ./docs/requirements.txt
+          pip install .
           python ./docs/build.py ${{ github.event.release.name }}
-
-      - name: Update README.md badges
-        run: |
           python ./docs/generate_readme_badges.py
 
       - name: Commit updated documentation and badges
         uses: "stefanzweifel    /git-auto-commit-action@v5"
         with:
           commit_message: Documentation for version ${{ github.event.release.name }}
+          branch: main

docs/build.py

@@ -11,10 +11,12 @@
 
 def build_docs_using_sphinx(version_number: str):
     print(f"Building docs for version v{version_number}")
-    python_path: str = sys.executable
     output_path: str = f'{curr_dir_path}/serve/v{version_number}'
-    run_command(
-        f"{python_path} -m sphinx.cmd.build -M html source {output_path}"
+    run_command([
+        sys.executable, '-m', 'sphinx.cmd.build', '-M', 'html', 'source', output_path,
+    ],
+        cwd=curr_dir_path,
+        raise_on_error=False
     )
     tmp_path: str = f'{output_path}@'
     shutil.move(output_path, tmp_path)

docs/generate_readme_badges.py

@@ -9,62 +9,70 @@
 
 
 # Documentation will be automatically generated on new version release
-def generate_tests_coverage_badge(python_path: str, cwd: str):
-    run_command(
-        f"{python_path} -m coverage run -m unittest discover ./tests",
+def generate_tests_coverage_badge(cwd: str):
+    run_command([
+        sys.executable, "-m", "coverage", "run", "-m", "unittest",  "discover", "./tests"
+    ],
         cwd=cwd
     )
-    run_command(
-        f"{python_path} -m coverage xml -o ./docs/reports/coverage/coverage.xml",
+    run_command([
+        sys.executable, "-m", "coverage", "xml", "-o", "./docs/reports/coverage/coverage.xml"
+    ],
         cwd=cwd
     )
-    run_command(
-        f"{python_path} -m coverage html -d ./docs/reports/coverage/",
+    run_command([
+        sys.executable, "-m", "coverage", "html", "-d", "./docs/reports/coverage/"
+    ],
         cwd=cwd
     )
-    run_command(
-        "genbadge coverage -i ./docs/reports/coverage/coverage.xml  -o ./docs/badges/coverage-badge.svg",
+    run_command([
+        "genbadge", "coverage", "-i", "./docs/reports/coverage/coverage.xml", "-o", "./docs/badges/coverage-badge.svg"
+    ],
         cwd=cwd
     )
 
 
-def generate_test_badge(python_path: str, cwd: str):
+def generate_test_badge(cwd: str):
     test_report_path = pathlib.Path(curr_dir_path / 'reports' / 'junit')
     shutil.rmtree(test_report_path)
     os.makedirs(test_report_path, exist_ok=True)
-    run_command(
-        f"{python_path} -m junitxml.main --o ./docs/reports/junit/junit.xml",
+    run_command([
+        sys.executable, "-m", "junitxml.main", "--o", "./docs/reports/junit/junit.xml"
+    ],
         cwd=cwd
     )
-    run_command(
-        f"{python_path} -m junit2htmlreport ./docs/reports/junit/junit.xml ./docs/reports/junit/report.html",
+    run_command([
+        sys.executable, "-m", "junit2htmlreport", "./docs/reports/junit/junit.xml", "./docs/reports/junit/report.html"
+    ],
         cwd=cwd
     )
-    run_command(
-        "genbadge tests -i ./docs/reports/junit/junit.xml -o ./docs/badges/test-badge.svg",
+    run_command([
+        "genbadge", "tests", "-i", "./docs/reports/junit/junit.xml", "-o", "./docs/badges/test-badge.svg"
+    ],
         cwd=cwd
     )
 
 
-def generate_flake8_badge(python_path: str, cwd: str):
-    run_command(
-        f"{python_path} -m flake8 ./rulekit --exit-zero --format=html --htmldir ./docs/reports/flake8 --statistics --tee --output-file ./docs/reports/flake8/flake8stats.txt",
+def generate_flake8_badge(cwd: str):
+    run_command([
+        sys.executable, "-m", "flake8", "./rulekit", "--exit-zero", "--format=html", "--htmldir", "./docs/reports/flake8", "--statistics", "--tee", "--output-file", "./docs/reports/flake8/flake8stats.txt"
+    ],
         cwd=cwd
     )
-    run_command(
-        "genbadge flake8 -i ./docs/reports/flake8/flake8stats.txt -o ./docs/badges/flake8-badge.svg",
+    run_command([
+        "genbadge", "flake8", "-i", "./docs/reports/flake8/flake8stats.txt", "-o", "./docs/badges/flake8-badge.svg"
+    ],
         cwd=cwd
     )
 
 
 def main():
     print('Updating badges')
     cwd = pathlib.Path(curr_dir_path / '..')  # root repo dir
-    python_path: str = sys.executable
 
-    generate_tests_coverage_badge(python_path, cwd)
-    generate_test_badge(python_path, cwd)
-    generate_flake8_badge(python_path, cwd)
+    generate_tests_coverage_badge(cwd)
+    generate_test_badge(cwd)
+    generate_flake8_badge(cwd)
 
     print('Badges generated successfully!')
 

docs/helpers.py

@@ -2,6 +2,17 @@
 from typing import Optional
 
 
-def run_command(command: str, cwd: Optional[str] = None):
-    output = subprocess.check_output(command, cwd=cwd)
+def run_command(command: list[str], cwd: Optional[str] = None, raise_on_error: bool = True):
+    process = subprocess.Popen(
+        command,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        cwd=cwd
+    )
+    output, error = process.communicate()
+    if process.returncode != 0 and raise_on_error:
+        raise Exception("File handling failed %d %s %s" %
+                        (process.returncode, output, error)
+                        )
+
     print(output.decode())

docs/requirements.txt

@@ -1,10 +1,12 @@
-Jinja2<3.1
 Sphinx==7.2.6
 sphinx-rtd-theme==2.0.0
 nbsphinx==0.9.3
 sphinx-copybutton==0.5.2
 ipykernel==5.5.0
 pandoc~=2.3
+coverage~=7.6.4
 ipython_genutils~=0.2.0
-../ 
-
+flake8
+junitxml==0.7
+junit2html~=31.0.2
+genbadge[all]~=1.1.1

docs/serve/index.html

@@ -116,27 +116,10 @@ <h1>
 
                 <li class="toctree-l1">
                     <a class="reference internal" href="v2.1.18.0/index.html">
-                        v2.1.18.0 
+                        v2.1.18.0 (latest)
                     </a>
                 </li>
 
-                <li class="toctree-l1">
-                    <a class="reference internal" href="v2.1.18.0/index.html">
-                        v2.1.18.0 
-                    </a>
-                </li>
-                
-                <li class="toctree-l1">
-                    <a class="reference internal" href="v2.18.0.0/index.html">
-                        v2.18.0.0 
-                    </a>
-                </li>
-                
-                <li class="toctree-l1">
-                    <a class="reference internal" href="v2.18.0.0/index.html">
-                        v2.18.0.0 (latest)
-                    </a>
-                </li>
                 <!-- LATEST VERSION PLACEHOLDER -->