Merge pull request #31 from adaa-polsl/github-actions

build: Github action building docs on each new release

Author: cezary986

.github/workflows/build_docs_on_new_release.yml

@@ -0,0 +1,33 @@
+name: Build docummentation and updated README badges on new release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build documentation
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r ./docs/requirements.txt
+          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 }}

docs/HOW_TO_DEPLOY.md

@@ -3,55 +3,15 @@
 > Don't forger to change version before deployment!
 > Deployment **MUST** be done from the `main` branch only!
 
-### 1. Update documentation on Github Pages
-> Make sure you installed docs dependencies in **SEPARATE** virtual env and activated it
-
-In `docs` directory call call:
-
-```bash
-build.py <VERSION_NUMBER>
-```
-e.g. 
-```bash
-build.py 2.18.0.0
-```
-
-### 2. Update badges
-
-In repo root directory:
-
-1. Update coverage badge
-```bash
-python -m coverage run -m unittest discover ./tests 
-python -m coverage xml -o ./docs/reports/coverage/coverage.xml  
-python -m coverage html -d ./docs/reports/coverage/
-genbadge coverage -i ./docs/reports/coverage/coverage.xml  -o ./docs/badges/coverage-badge.svg
-```
-
-2. Update test badge
-
-```bash
-rm -r ./docs/reports/junit
-mkdir ./docs/reports/junit
-python -m junitxml.main --o ./docs/reports/junit/junit.xml
-python -m junit2htmlreport ./docs/reports/junit/junit.xml ./docs/reports/junit/report.html
-genbadge tests -i ./docs/reports/junit/junit.xml -o ./docs/badges/test-badge.svg
-```
-
-3. Update flake8 badge
-
-```bash
-flake8 ./rulekit --exit-zero --format=html --htmldir ./docs/reports/flake8 --statistics --tee --output-file ./docs/reports/flake8/flake8stats.txt
-genbadge flake8 -i ./docs/reports/flake8/flake8stats.txt -o ./docs/badges/flake8-badge.svg
-```
-
-### 3. Create tag in Github repository 
+### 1. Create tag in Github repository 
 Create tag on current commit named `v{CURRENT_VERSION}`
 
-### 4. Create deployment in Github
+### 2. Create release in Github
 Use previously created tag for it.
 
-### 5. Deploy to pypi
+> Documentation will be automatically generated on new version release 
+
+### 3. Deploy to pypi
 In root repository directory:
 ```
 rm -r ./dist

docs/badges/flake8-badge.svg

@@ -1,33 +1,30 @@
 import argparse
 import os
+import pathlib
 import shutil
-import subprocess
 import sys
 
-curr_dir_path: str = os.path.dirname(os.path.realpath(__file__))
+from helpers import run_command
+
+curr_dir_path: str = pathlib.Path(os.path.realpath(__file__)).parent
 
 
 def build_docs_using_sphinx(version_number: str):
     print(f"Building docs for version v{version_number}")
-    if version_number[0] == 'v':
-        raise ValueError(
-            'Please provide version number without "v" prefix')
-
     python_path: str = sys.executable
     output_path: str = f'{curr_dir_path}/serve/v{version_number}'
-    output = subprocess.check_output(
+    run_command(
         f"{python_path} -m sphinx.cmd.build -M html source {output_path}"
     )
-    print(output.decode())
-
     tmp_path: str = f'{output_path}@'
     shutil.move(output_path, tmp_path)
-    shutil.move(os.path.join(tmp_path, 'html'), output_path)
+    shutil.move(pathlib.Path(tmp_path, 'html'), output_path)
     shutil.rmtree(tmp_path)
 
 
 def update_index_html(version_number: str):
-    with open(os.path.join(curr_dir_path, 'serve', 'index.html'), 'r', encoding='utf-8') as index_html:
+    print('Updating index.html...')
+    with open(pathlib.Path(curr_dir_path / 'serve' / 'index.html'), 'r', encoding='utf-8') as index_html:
         content: str = index_html.read()
         content = content.replace('(latest)', '')
         content = content.replace(
@@ -41,7 +38,7 @@ def update_index_html(version_number: str):
                 <!-- LATEST VERSION PLACEHOLDER -->
             '''
         )
-    with open(os.path.join(curr_dir_path, 'serve', 'index.html'), 'w', encoding='utf-8') as index_html:
+    with open(pathlib.Path(curr_dir_path / 'serve' / 'index.html'), 'w', encoding='utf-8') as index_html:
         index_html.write(content)
 
 
@@ -52,8 +49,14 @@ def main():
     parser.add_argument('version_number')
     args = parser.parse_args()
 
-    build_docs_using_sphinx(args.version_number)
-    update_index_html(args.version_number)
+    version_number: str = args.version_number
+    # remove "v" prefix if present
+    if version_number.startswith('v'):
+        version_number = version_number.replace('v', '')
+
+    build_docs_using_sphinx(version_number)
+    update_index_html(version_number)
+    print('Documentation built successfully!')
 
 
 if __name__ == "__main__":

docs/build.py

@@ -0,0 +1,73 @@
+import os
+import pathlib
+import shutil
+import sys
+
+from helpers import run_command
+
+curr_dir_path: str = pathlib.Path(os.path.realpath(__file__)).parent
+
+
+# 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",
+        cwd=cwd
+    )
+    run_command(
+        f"{python_path} -m coverage xml -o ./docs/reports/coverage/coverage.xml",
+        cwd=cwd
+    )
+    run_command(
+        f"{python_path} -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",
+        cwd=cwd
+    )
+
+
+def generate_test_badge(python_path: str, 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",
+        cwd=cwd
+    )
+    run_command(
+        f"{python_path} -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",
+        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",
+        cwd=cwd
+    )
+    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)
+
+    print('Badges generated successfully!')
+
+
+if __name__ == "__main__":
+    main()

docs/generate_readme_badges.py

@@ -0,0 +1,7 @@
+import subprocess
+from typing import Optional
+
+
+def run_command(command: str, cwd: Optional[str] = None):
+    output = subprocess.check_output(command, cwd=cwd)
+    print(output.decode())

docs/helpers.py

@@ -54,8 +54,8 @@ <h2>
                 <a class="button current">Classes</a>
         </h2>
         <p class="text">
-            <a class="nav" href="https://coverage.readthedocs.io/en/7.6.1">coverage.py v7.6.1</a>,
-            created at 2024-09-09 11:15 +0200
+            <a class="nav" href="https://coverage.readthedocs.io/en/7.6.4">coverage.py v7.6.4</a>,
+            created at 2024-11-05 13:43 +0100
         </p>
     </div>
 </header>
@@ -771,8 +771,8 @@ <h2>
 <footer>
     <div class="content">
         <p>
-            <a class="nav" href="https://coverage.readthedocs.io/en/7.6.1">coverage.py v7.6.1</a>,
-            created at 2024-09-09 11:15 +0200
+            <a class="nav" href="https://coverage.readthedocs.io/en/7.6.4">coverage.py v7.6.4</a>,
+            created at 2024-11-05 13:43 +0100
         </p>
     </div>
     <aside class="hidden">

docs/reports/coverage/class_index.html

@@ -54,8 +54,8 @@ <h2>
                 <a class="button" href="class_index.html">Classes</a>
         </h2>
         <p class="text">
-            <a class="nav" href="https://coverage.readthedocs.io/en/7.6.1">coverage.py v7.6.1</a>,
-            created at 2024-09-09 11:15 +0200
+            <a class="nav" href="https://coverage.readthedocs.io/en/7.6.4">coverage.py v7.6.4</a>,
+            created at 2024-11-05 13:43 +0100
         </p>
     </div>
 </header>
@@ -2435,8 +2435,8 @@ <h2>
 <footer>
     <div class="content">
         <p>
-            <a class="nav" href="https://coverage.readthedocs.io/en/7.6.1">coverage.py v7.6.1</a>,
-            created at 2024-09-09 11:15 +0200
+            <a class="nav" href="https://coverage.readthedocs.io/en/7.6.4">coverage.py v7.6.4</a>,
+            created at 2024-11-05 13:43 +0100
         </p>
     </div>
     <aside class="hidden">

docs/reports/coverage/function_index.html

@@ -53,8 +53,8 @@ <h2>
                 <a class="button" href="class_index.html">Classes</a>
         </h2>
         <p class="text">
-            <a class="nav" href="https://coverage.readthedocs.io/en/7.6.1">coverage.py v7.6.1</a>,
-            created at 2024-09-09 11:15 +0200
+            <a class="nav" href="https://coverage.readthedocs.io/en/7.6.4">coverage.py v7.6.4</a>,
+            created at 2024-11-05 13:43 +0100
         </p>
     </div>
 </header>
@@ -256,8 +256,8 @@ <h2>
 <footer>
     <div class="content">
         <p>
-            <a class="nav" href="https://coverage.readthedocs.io/en/7.6.1">coverage.py v7.6.1</a>,
-            created at 2024-09-09 11:15 +0200
+            <a class="nav" href="https://coverage.readthedocs.io/en/7.6.4">coverage.py v7.6.4</a>,
+            created at 2024-11-05 13:43 +0100
         </p>
     </div>
     <aside class="hidden">