Contributing and CI Improvements (#292)

* add nox and npm info to guidelines
* reuse CI font cache from docs build in test

.github/workflows/build.yml

@@ -116,7 +116,13 @@ jobs:
         uses: ts-graphviz/setup-graphviz@c001ccfb5aff62e28bda6a6c39b59a7e061be5b9 # v1.2.0
         with:
           macos-skip-brew-update: 'true'
+      - uses: actions/cache@v3
+        with:
+          path: ${{ github.workspace }}/theme_build_cache
+          key: theme-build-cache-${{ runner.os }}-${{ github.run_id }}
       - name: Build docs
+        env:
+          SPHINX_IMMATERIAL_EXTERNAL_RESOURCE_CACHE_DIR: ${{ github.workspace }}/theme_build_cache
         run: nox -s docs
       - name: Upload doc builds as artifacts
         uses: actions/upload-artifact@v3
@@ -131,7 +137,7 @@ jobs:
           publish_dir: ./docs/_build/html
 
   test:
-    needs: [check_conventions]
+    needs: [check_conventions, build]
     strategy:
       fail-fast: false
       matrix:
@@ -176,8 +182,13 @@ jobs:
         uses: ts-graphviz/setup-graphviz@c001ccfb5aff62e28bda6a6c39b59a7e061be5b9 # v1.2.0
         with:
           macos-skip-brew-update: 'true'
+      - uses: actions/cache/restore@v3
+        with:
+          path: ${{ github.workspace }}/theme_build_cache
+          key: theme-build-cache-${{ runner.os }}-${{ github.run_id }}
       - name: Run Python tests
         env:
+          SPHINX_IMMATERIAL_EXTERNAL_RESOURCE_CACHE_DIR: ${{ github.workspace }}/theme_build_cache
           COVERAGE_FILE: .coverage.${{ github.run_id }}.${{ github.run_attempt }}.${{ runner.os }}.${{ matrix.python-version }}.${{ matrix.sphinx-version }}
         # `coverage run` cmd adds the working dir to python path, so no need to install pkg here
         run: pipx run nox -s "tests-${{ matrix.python-version }}(${{ matrix.sphinx-version }})"

CONTRIBUTING.md

@@ -10,6 +10,29 @@ We use linters to keep our code style conventional. Thus, this repository is set
 
 Please be sure to review/format your code changes in accordance with the style guides incorporated in this repository (which are typically named _.**rc_).
 
+### Using `nox` & `npm`
+
+Most of our CI uses a program utility called `nox`.
+For JS and SCSS checking, we use `npm` tasks.
+
+#### Run type checkers and formatters for Python
+
+Be sure `nox` is installed via `pip install nox`.
+
+From the repository root directory:
+
+```shell
+nox
+```
+
+More info is available via `nox -h` or [their documentation](https://nox.thea.codes/en/stable/usage.html).
+
+#### Run type checkers and formatters for JS & SCSS
+
+```shell
+npm run check
+```
+
 ## Unwanted changes
 
 Anything contained within the _src_ folder is meant to be merged from the upstream mkdocs-material repo. As such, it is discouraged from making any changes that might cause a merge conflict when new changes are pulled from the upstream repository.