CI/FIX: improve gh actions

closes #624

.github/workflows/docs.yml

@@ -1,12 +1,22 @@
 name: Build Documentation
 
+
 on:
-  workflow_dispatch:
   workflow_call:
     inputs:
       publish:
         required: true
         type: boolean
+  workflow_dispatch:
+    inputs:
+      publish:
+        required: true
+        type: boolean
+      pin-tag:
+        # pin-tag can be used to keep the latest X.Y.Z release tag instead of
+        # a X.Y.Z-devN tag when updating the docs after a release
+        required: false
+        type: string
   release:
     types: [ released ]
 
@@ -18,6 +28,7 @@ env:
 
 jobs:
   build_docs:
+    if: (!contains(github.event.head_commit.message, '[skip-doc-build]')) || inputs.publish
     name: Build Documentation
     runs-on: ubuntu-latest
     steps:
@@ -58,10 +69,20 @@ jobs:
           restore-keys: |
             fastf1-doc-cache
 
+      - name: Install at pinned tag
+        if: inputs.pin-tag != ''
+        run: |
+          git checkout ${{ inputs.pin-tag }}
+
       - name: Install Fast-F1 from sources
         run: |
           python -m pip install -e .
 
+      - name: Re-checkout current commit after install at pinned tag
+        if: inputs.pin-tag != ''
+        run: |
+          git checkout ${{ github.sha }}
+
       - name: Create doc build dir
         run: |
           mkdir -p docs/_build/html
@@ -75,18 +96,28 @@ jobs:
       - name: Build docs
         run: |
           mkdir test_cache  # not really need but pytest setup relies on it 
-          cd ./docs
-          make clean
+          
+          # delete all files in build directory, will be replaced with new 
+          # build (don't use "make clean" as it deletes the .git folder)
+          # need to go to nested git repository in build directory
+          cd ./docs/_build/html
+          git rm -r *  
+          
+          # go back to docs folder in main repository
+          cd ../..
           make html
 
-      - name: Publish docs
-        if: (github.event_name == 'release') || inputs.publish
+      - name: Prepare docs for publishing
         run: |
           cd docs/_build/html
           git add .
           git config user.name github-actions
           git config user.email [email protected]
           git commit -m "$GITHUB_REF_NAME ($GITHUB_JOB) ci release"
+
+      - name: Publish docs
+        if: (github.event_name == 'release') || inputs.publish
+        run: |
           git push origin gh-pages --force
 
       - name: Upload docs as artifact

.github/workflows/tests.yml

@@ -15,6 +15,7 @@ env:
 
 jobs:
   run-code-tests:
+    if: (!contains(github.event.head_commit.message, '[skip-pytest]'))
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -75,6 +76,7 @@ jobs:
 
 
   run-lint-checks:
+    if: (!contains(github.event.head_commit.message, '[skip-ruff]'))
     runs-on: ubuntu-latest
     name: Linting (Ruff)
     steps:
@@ -111,6 +113,7 @@ jobs:
 
 
   run-isort-test:
+    if: (!contains(github.event.head_commit.message, '[skip-isort]'))
     name: Test import order (isort)
     runs-on: ubuntu-latest
 
@@ -141,6 +144,7 @@ jobs:
           python -m isort . --check-only
 
   run-readme-render-test:
+    if: (!contains(github.event.head_commit.message, '[skip-readme-test]'))
     name: Test readme renders on PyPi
     runs-on: ubuntu-latest
 

docs/contributing/testing.rst

@@ -53,9 +53,8 @@ not need to be installed, but FastF1 should be)::
 .. _command-line parameters: http://doc.pytest.org/en/latest/usage.html
 
 
-==========================
 Linting - Code style tests
-==========================
+--------------------------
 
 FastF1 uses Ruff_ and isort_ to ensure that the code has a consistent style and
 is easily readable. All code should conform to the guidelines that are defined
@@ -76,4 +75,21 @@ these commands will also be run automatically before each commit.
 
 .. _Ruff: https://docs.astral.sh/ruff/
 .. _isort: https://pycqa.github.io/isort/
-.. _PEP8: https://pep8.org/
+.. _PEP8: https://pep8.org/
+
+
+Github Actions CI Tests
+-----------------------
+
+FastF1 uses Github Actions to run the tests on every push to the repository and
+when updating a pull request. Usually, you should just let all tests run and
+make sure that they are passing.
+
+In rare cases, it may be usefull to skip some tests. You can do this by adding
+a specific comment to the commit message. The following comments are supported:
+
+- ``[skip-pytest]``: Skip pytest runs on all Python versions
+- ``[skip-ruff]``: Skip Ruff code style checks
+- ``[skip-isort]``: Skip isort import order checks
+- ``[skip-doc-build]``: Skip building the documentation
+- ``[skip-readme-test]``: Skip the README render test for PyPI