From f7122370347fdba966a0ef5fa7df9d5e023e41b9 Mon Sep 17 00:00:00 2001 From: "Storm B. Heg" Date: Thu, 7 Mar 2024 15:49:20 +0100 Subject: [PATCH 01/20] Lowercase github workflow file name for consistency --- .github/workflows/{CI.yml => ci.yml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename .github/workflows/{CI.yml => ci.yml} (100%) diff --git a/.github/workflows/CI.yml b/.github/workflows/ci.yml similarity index 100% rename from .github/workflows/CI.yml rename to .github/workflows/ci.yml From f50e205e9b91186e92b64343aa4df10c59e09fac Mon Sep 17 00:00:00 2001 From: "Storm B. Heg" Date: Thu, 7 Mar 2024 16:09:10 +0100 Subject: [PATCH 02/20] Remove Github Pages deploy We don't appear to use this. --- .github/workflows/ci.yml | 17 ----------------- 1 file changed, 17 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7bdd9ddb..682351b5 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -87,20 +87,3 @@ jobs: echo 'html_theme = "'${html_theme}'"' >> source/conf.py cat source/conf.py sphinx-build -b html -A version=test source build - - deploy: - runs-on: ubuntu-latest - needs: build - if: github.event_name == 'push' && github.ref == 'refs/heads/main' - steps: - - uses: actions/checkout@v3 - - uses: actions/download-artifact@v2 - with: - name: static-files - path: sphinx_wagtail_theme/static/dist/ - - run: grep -F -v 'dist' .gitignore > .gitignore.tmp && mv .gitignore.tmp .gitignore - - uses: JamesIves/github-pages-deploy-action@4.1.1 - with: - branch: gh-pages - folder: . - clean: true From a470406ff10acc13b839df8fb81d5d894a9e1f15 Mon Sep 17 00:00:00 2001 From: "Storm B. Heg" Date: Thu, 7 Mar 2024 16:11:23 +0100 Subject: [PATCH 03/20] Remove sphinx-quickstart job Looks like a smoke test to check the sphinx build process does not crash. We can do this in a way the can more easily run locally. --- .github/workflows/ci.yml | 25 ------------------------- 1 file changed, 25 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 682351b5..fb3e4c0c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -62,28 +62,3 @@ jobs: - run: make docs - name: Percy Test run: make test-visual-regression - - sphinx-quickstart: - needs: [build] - runs-on: ubuntu-latest - steps: - - uses: actions/download-artifact@v1 - with: - name: bdist-wheel-package - path: packages - - uses: actions/setup-python@v4 - with: - python-version: '3.10' - - run: pip install sphinx - - run: pip install $(find packages -name "*.whl") - - name: Assert is importable, show version - run: python -c "import sphinx_wagtail_theme; print(sphinx_wagtail_theme.__version__)" - - run: | - html_theme=sphinx_wagtail_theme - sphinx-quickstart --project PROJECT --author AUTHOR --sep \ - --extensions ${html_theme} --no-use-make-mode --quiet - echo >> source/conf.py - echo 'extensions.append("'${html_theme}'")' >> source/conf.py - echo 'html_theme = "'${html_theme}'"' >> source/conf.py - cat source/conf.py - sphinx-build -b html -A version=test source build From d734d81e0ff3cc106fd7d0741f4f58d5fcaa5fab Mon Sep 17 00:00:00 2001 From: "Storm B. Heg" Date: Thu, 7 Mar 2024 16:14:47 +0100 Subject: [PATCH 04/20] Remove build job as it now unused We used this for the sphinx-quickstart and github actions deploy. --- .github/workflows/ci.yml | 25 ------------------------- 1 file changed, 25 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index fb3e4c0c..fb6428ad 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -7,31 +7,6 @@ on: pull_request: jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - id: nvm - run: echo "##[set-output name=NVMRC;]$(cat .nvmrc)" - - uses: actions/setup-node@v3 - with: - node-version: '${{ steps.nvm.outputs.NVMRC }}' - - run: npm install - - run: npm run build - - uses: actions/setup-python@v4 - with: - python-version: '3.10' - - run: pip install wheel - - run: python setup.py bdist_wheel - - uses: actions/upload-artifact@v1 - with: - name: bdist-wheel-package - path: dist - - uses: actions/upload-artifact@v1 - with: - name: static-files - path: sphinx_wagtail_theme/static/dist/ - test: runs-on: ubuntu-latest steps: From da1ae7c92662a6fe033d7e9a36be1e3561821177 Mon Sep 17 00:00:00 2001 From: "Storm B. Heg" Date: Thu, 7 Mar 2024 16:16:03 +0100 Subject: [PATCH 05/20] Update github action versions Use Node 20 instead of 16, because actions using v16 are deprecated. https://github.blog/changelog/2023-09-22-github-actions-transitioning-from-node-16-to-node-20/ --- .github/workflows/ci.yml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index fb6428ad..f84cf577 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -10,10 +10,10 @@ jobs: test: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 - - uses: actions/setup-python@v4 + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 with: - python-version: '3.10' + python-version: '3.12' - run: make setup - run: make install-for-development - run: make lint-minimal @@ -25,10 +25,10 @@ jobs: env: PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }} steps: - - uses: actions/checkout@v3 - - uses: actions/setup-python@v4 + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 with: - python-version: '3.10' + python-version: '3.12' - name: Setup Firefox and geckodriver uses: ./.github/actions/setup-firefox - run: make setup From 92569f9a67e4317442c3163045f4b34cad385b1a Mon Sep 17 00:00:00 2001 From: "Storm B. Heg" Date: Thu, 7 Mar 2024 16:41:46 +0100 Subject: [PATCH 06/20] Fix Firefox headless mode See https://www.selenium.dev/blog/2023/headless-is-going-away/ --- tests/test_visual_regression.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tests/test_visual_regression.py b/tests/test_visual_regression.py index 8bca245f..dea22e6a 100644 --- a/tests/test_visual_regression.py +++ b/tests/test_visual_regression.py @@ -4,7 +4,7 @@ import percy from selenium import webdriver -from selenium.webdriver.firefox import options as firefox_options +from selenium.webdriver.firefox.options import Options as FirefoxOptions BASE_DIR = pathlib.Path(__file__).parent.parent.resolve() @@ -33,8 +33,8 @@ def main(): server_thread.start() print("Server thread running. Starting client requests...") - options = firefox_options.Options() - options.headless = True + options = FirefoxOptions() + options.add_argument("--headless") driver = webdriver.Firefox(options=options) def take_snapshot(url, title): From 47a15035ee82e7b8820aa552e8043534287403df Mon Sep 17 00:00:00 2001 From: "Storm B. Heg" Date: Thu, 7 Mar 2024 16:46:47 +0100 Subject: [PATCH 07/20] Update makefile lint tasks Not sure why we had a lint-minimal tasks. Code is either linted or not. There is no in-between lower standard. --- .github/workflows/ci.yml | 16 +++++++++++++--- Makefile | 24 ++++++++---------------- 2 files changed, 21 insertions(+), 19 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f84cf577..4b809f66 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -7,7 +7,18 @@ on: pull_request: jobs: - test: + frontend_qa: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: '20' + - run: make frontend + - run: make lint-frontend + - run: make test + + python_qa: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 @@ -16,8 +27,7 @@ jobs: python-version: '3.12' - run: make setup - run: make install-for-development - - run: make lint-minimal - - run: npm run lint + - run: make lint-python - run: make test visual-regression-tests: diff --git a/Makefile b/Makefile index 730297d4..c0b44893 100644 --- a/Makefile +++ b/Makefile @@ -145,27 +145,19 @@ install-for-development: clean uninstall ## Clean, uninstall and pip install -e .PHONY: lint -lint: ## Check Python style +lint: lint-python lint-frontend ##- Run all linters + + +.PHONY: lint-python +lint-python: flake8 *.py flake8 sphinx_wagtail_theme flake8 tests -.PHONY: lint-minimal lm -lm: lint-minimal -lint-minimal: ## Check Python style for minimal standards (alias lm) - flake8 *.py --count --select=E9,F63,F7,F82 --show-source --statistics - echo - flake8 sphinx_wagtail_theme --count --select=E9,F63,F7,F82 --show-source --statistics - echo - flake8 tests --count --select=E9,F63,F7,F82 --show-source --statistics - echo - flake8 *.py --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics - echo - flake8 sphinx_wagtail_theme --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics - echo - flake8 tests --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics - echo +.PHONY: lint-frontend +lint-frontend: + npm run lint .PHONY: release From b75b13215f479f2daf5f2121e7c8e23cd5dabe7f Mon Sep 17 00:00:00 2001 From: "Storm B. Heg" Date: Thu, 7 Mar 2024 16:54:48 +0100 Subject: [PATCH 08/20] Enable caching of NPM dependencies in CI --- .github/workflows/ci.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4b809f66..ce6a81a1 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -14,9 +14,10 @@ jobs: - uses: actions/setup-node@v4 with: node-version: '20' - - run: make frontend + cache: 'npm' + - run: npm ci - run: make lint-frontend - - run: make test + - run: make frontend python_qa: runs-on: ubuntu-latest From 9d19d25ab6adbcc27e07d6a8b0a1785e108fff53 Mon Sep 17 00:00:00 2001 From: "Storm B. Heg" Date: Thu, 7 Mar 2024 16:59:21 +0100 Subject: [PATCH 09/20] Replace setup firefox action This action supports caching and is one less moving part to worry about. --- .github/actions/setup-firefox/action.yml | 14 -------------- .github/workflows/ci.yml | 7 +++++-- 2 files changed, 5 insertions(+), 16 deletions(-) delete mode 100644 .github/actions/setup-firefox/action.yml diff --git a/.github/actions/setup-firefox/action.yml b/.github/actions/setup-firefox/action.yml deleted file mode 100644 index 6241d119..00000000 --- a/.github/actions/setup-firefox/action.yml +++ /dev/null @@ -1,14 +0,0 @@ -# Shamelessly copied from https://github.com/SeleniumHQ/selenium/blob/5d108f9a679634af0bbc387e7e3811bc1565912b/.github/actions/setup-firefox/action.yml -name: 'Setup Firefox and geckodriver' -runs: - using: 'composite' - steps: - - run: | - GECKODRIVER_URL=`curl -Ls -o /dev/null -w %{url_effective} https://github.com/mozilla/geckodriver/releases/latest` - GECKODRIVER_VERSION=`echo $GECKODRIVER_URL | sed 's#.*/##'` - export GECKODRIVER_DOWNLOAD="https://github.com/mozilla/geckodriver/releases/download/$GECKODRIVER_VERSION/geckodriver-$GECKODRIVER_VERSION-linux64.tar.gz" - curl -L -o geckodriver.tar.gz $GECKODRIVER_DOWNLOAD - gunzip -c geckodriver.tar.gz | tar xopf - - chmod +x geckodriver && sudo mv geckodriver /usr/local/bin - geckodriver --version - shell: bash diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ce6a81a1..154308bb 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -37,11 +37,14 @@ jobs: PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }} steps: - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' - uses: actions/setup-python@v5 with: python-version: '3.12' - - name: Setup Firefox and geckodriver - uses: ./.github/actions/setup-firefox + - uses: browser-actions/setup-firefox@v1 - run: make setup - run: make install-for-development - run: make frontend From f27268b03c501581e10220af9a358fbdf80a1f59 Mon Sep 17 00:00:00 2001 From: "Storm B. Heg" Date: Thu, 7 Mar 2024 17:41:09 +0100 Subject: [PATCH 10/20] Clean up the makefile even further --- .eslintignore | 1 - .github/workflows/ci.yml | 10 +-- .gitignore | 7 +- Makefile | 142 +++++++++++++-------------------------- build/.gitkeep | 0 docs/development.rst | 33 ++------- requirements-dev.txt | 1 - setup.cfg | 4 -- 8 files changed, 57 insertions(+), 141 deletions(-) delete mode 100644 build/.gitkeep diff --git a/.eslintignore b/.eslintignore index 9e91e20a..8e3bd75b 100644 --- a/.eslintignore +++ b/.eslintignore @@ -2,7 +2,6 @@ node_modules *.min.js **/lib/ public/ -coverage/ **/vendor/ docs/_build sphinx_wagtail_theme/static diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 154308bb..61dff018 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -26,8 +26,7 @@ jobs: - uses: actions/setup-python@v5 with: python-version: '3.12' - - run: make setup - - run: make install-for-development + - run: make install-python - run: make lint-python - run: make test @@ -45,9 +44,10 @@ jobs: with: python-version: '3.12' - uses: browser-actions/setup-firefox@v1 - - run: make setup - - run: make install-for-development - - run: make frontend + - run: make install-python + - run: npm ci + # Check against the dist version of the frontend, as it would be appear when deployed + - run: make frontend-dist - run: make docs - name: Percy Test run: make test-visual-regression diff --git a/.gitignore b/.gitignore index 08d3c024..98412e61 100644 --- a/.gitignore +++ b/.gitignore @@ -2,11 +2,6 @@ *.egg *.egg-info *.pyc -*.sass-cache -*GENERATED* -*NOT_VERSIONED* -.coverage -.eggs/ .idea .ruby-version .tox @@ -22,7 +17,7 @@ npm-debug.log /.vscode /build/* -!/build/.gitkeep +rtd-env/ venv/ env/ .env/ diff --git a/Makefile b/Makefile index c0b44893..48b65d83 100644 --- a/Makefile +++ b/Makefile @@ -25,13 +25,13 @@ for target, help in hits: print("%-20s %s" % (target, help)) print(""" Start with the installation of Python and Node modules: - make setup + make install Compile frontend changes: make frontend -Build, import from package, test, render the repo docs and open in browser: - make install test-import docs +Build example docs and open in browser: + make docs serve """) endef export PRINT_HELP_PYSCRIPT @@ -44,70 +44,58 @@ help: @python -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST) -.PHONY: build -build: clean build-project ## Build all, except frontend +.PHONY: install +install: install-python install-frontend ## Install all -.PHONY: build-project -build-project: clean-project ##- Build Sphinx extension - python setup.py sdist - python setup.py bdist_wheel - ls -l dist +.PHONY: install-frontend +install-frontend: ##- Install node modules + npm install -.PHONY: clean -clean: clean-project ## Clean all, except frontend +.PHONY: install-python +install-python: ##- Install Python modules + pip install -U pip + pip install -U -r requirements.txt + pip install -U -r requirements-dev.txt -.PHONY: clean-project -clean-project: clean-build clean-pyc clean-test clean-docs ## Remove all build, test, coverage and Python artifacts +.PHONY: build +build: clean frontend-dist ##- Build Sphinx extension + python -m build + ls -l dist + +.PHONY: clean +clean: ##- Remove all build, test and Python artifacts + # Build frontend files + rm -rf sphinx_wagtail_theme/static/dist -.PHONY: clean-build -clean-build: ##- Remove build artifacts + # Python build artifacts rm -rf build/ - mkdir -p build - touch build/.gitkeep rm -rf dist/ rm -rf .eggs/ find . -name '*.egg-info' -exec rm -rf {} + find . -name '*.egg' -exec rm -f {} + + # Clean build docs + rm -rf ./docs/_build + rm -rf ./rtd-venv -.PHONY: clean-frontend -clean-frontend: ## Clean frontend files - rm -rf sphinx_wagtail_theme/static/dist + # Python test artifacts + rm -rf .tox/ + rm -rf htmlcov/ + rm -rf .pytest_cache -clean-pyc: ##- Remove Python file artifacts + # Python artifacts find . -name '*.pyc' -exec rm -f {} + find . -name '*.pyo' -exec rm -f {} + find . -name '*~' -exec rm -f {} + find . -name '__pycache__' -exec rm -rf {} + -.PHONY: clean-test -clean-test: ##- Remove test and coverage artifacts - rm -rf .tox/ - rm -f .coverage - rm -rf htmlcov/ - rm -rf .pytest_cache - - -.PHONY: clean-docs -clean-docs: ##- Remove previously built docs - rm -rf ./docs/_build - rm -rf ./rtd-venv - - -.PHONY: coverage -coverage: ##- Check code coverage quickly with default Python - coverage run --source sphinx_wagtail_theme -m pytest - coverage report -m - coverage html - $(BROWSER) htmlcov/index.html - .PHONY: docs -docs: ## Regenerate Sphinx HTML documentation +docs: ## Build Sphinx HTML documentation $(MAKE) -C docs clean $(MAKE) -C docs html @@ -122,6 +110,7 @@ rtd-docs: ## Build the docs like Readthedocs does. ./rtd-venv/bin/python -m sphinx -T -E -b html -d ./docs/_build/doctrees -D language=en ./docs ./docs/_build/html rm -rf "./rtd-venv" + .PHONY: serve serve: ## Serve docs at http://localhost:8000 python -m http.server --directory ./docs/_build/html @@ -132,16 +121,21 @@ frontend: ## Compile frontend files npm run frontend -.PHONY: install -install: clean build uninstall ## Build Sphinx extension and install from package - find dist -name "*.whl" -print0 | xargs -0 pip install --upgrade +.PHONY: frontend-dist +frontend-dist: ##- Build frontend files for distribution + npm run build -.PHONY: install-for-development ifd -ifd: install-for-development -install-for-development: clean uninstall ## Clean, uninstall and pip install -e for development (alias ifd) - pip install -r requirements-dev.txt - pip install -e . +.PHONY: watch +watch: + npm run watch + + + +.PHONY: watchdocs +watchdocs: docs ##- Redo 'docs' and watch for changes (=make sd) + pip install watchdog + watchmedo shell-command -p '*.rst' -c '$(MAKE) -C docs html' -R -D . .PHONY: lint @@ -160,54 +154,12 @@ lint-frontend: npm run lint -.PHONY: release -release: dist ##- Clean, build and upload a release - echo TO BE DONE: twine upload dist/* - - -.PHONY: servedocs sd -sd: servedocs -servedocs: docs ##- Redo 'docs' and watch for changes (=make sd) - watchmedo shell-command -p '*.rst' -c '$(MAKE) -C docs html' -R -D . - - -.PHONY: setup -setup: setup-python setup-frontend ## Setup all - - -.PHONY: setup-frontend -setup-frontend: ##- Setup node modules - npm install - - -.PHONY: setup-python -setup-python: ##- Setup Python modules - pip install -U pip - pip install -U -r requirements.txt - - .PHONY: test -test: ## Run Python tests quickly with pytest +test: pytest - if [ -d dist ]; then find dist -name *.whl -exec twine check {} +; fi - -.PHONY: test-tox -test-tox: ##- Run tests on every Python version with tox - tox - - -.PHONY: test-import -test-import: ## Verify the extension is install and can be imported - python3 -c "import sphinx_wagtail_theme as m; print(m.__version__)" - python3 -c "import sphinx_wagtail_theme as m, pprint; pprint.pprint(m.__version_full__)" .PHONY: test-visual-regression test-visual-regression: ## Run visual regression tests ./node_modules/.bin/percy exec -- python tests/test_visual_regression.py -.PHONY: uninstall ui -ui: uninstall -uninstall: ##- Uninstall the extension - pip uninstall -y sphinx-wagtail-theme - diff --git a/build/.gitkeep b/build/.gitkeep deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/development.rst b/docs/development.rst index 01b3bdd5..1abc7948 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -7,7 +7,7 @@ Development =========== -For local development you need a system with Node v18.x, Python3, and Git. +For local development you need a system with Node v20.x, Python3, and Git. It is strongly recommended to use a Python virtual environment (`venv`_). The build process derives the version from repository data, so it's necessary to clone the repository and not just download a single snapshot. @@ -29,7 +29,7 @@ Install requirements and fulfill Python and Node demands (repeatable) .. code-block:: text - make setup + make install When doing frontend development compile your changes at any time @@ -37,18 +37,6 @@ When doing frontend development compile your changes at any time make frontend -Build and install the package - -.. code-block:: text - - make install - -Build and install the package for development - -.. code-block:: text - - make install-for-development - Don't forget to update the docs. Render the documentation .. code-block:: text @@ -61,31 +49,18 @@ Serve build docs locally make serve -Check the Python code. The CI workflow requires ``lint-minimal`` to succeed +Check the Python code and CSS/JS against the styleguide. .. code-block:: shell - # for local use make lint - # used in the workflow - make lint-minimal - Run Python unit tests .. code-block:: text make test -Rebuild and install from Python wheel package - -.. code-block:: shell - - make install - - # then verify the module can be imported and used - make test-import - To find out whether the created wheel package passes the `twine check` test and can be uploaded to PyPi run @@ -106,7 +81,7 @@ rather than using the shortcuts in the Makefile. Assume the commands below are all run in PowerShell. These instructions will also work on Mac or Linux without make installed as well. -First, be sure to install Python 3, and Node 18. +First, be sure to install Python 3, and Node 20. `fnm `_ is really useful for managing multiple versions of Node on Windows. diff --git a/requirements-dev.txt b/requirements-dev.txt index c8518430..1b880c8f 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -11,5 +11,4 @@ pytest selenium setuptools twine -wheel zest.releaser diff --git a/setup.cfg b/setup.cfg index 59fb68bd..09e98b15 100644 --- a/setup.cfg +++ b/setup.cfg @@ -30,10 +30,6 @@ python_requires = >=3.8 include_package_data = True -[bdist_wheel] -universal = 1 - - [flake8] exclude = .*,docs,node_modules,CVS,__pycache__,*.egg,*GENERATED* max-line-length = 127 From 802006aa081693c1b16d530ba78a487fd34bd9f9 Mon Sep 17 00:00:00 2001 From: "Storm B. Heg" Date: Thu, 7 Mar 2024 17:56:38 +0100 Subject: [PATCH 11/20] Add trusted publishing workflow --- .github/workflows/publish.yml | 60 +++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 .github/workflows/publish.yml diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 00000000..0e98c501 --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,60 @@ +name: Publish to PyPI +on: + release: + # https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#release + types: [released] +jobs: + test: + uses: ./.github/workflows/ci.yml + + build: + needs: ['test'] + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-node@v4 + with: + node-version: 20 + cache: npm + + - name: Install Node dependencies + run: | + npm ci + + - name: Compile JavaScript + run: | + make frontend-dist + + - uses: actions/setup-python@v5 + with: + python-version: 3.12 + + - name: Install dependencies + run: make setup-python + + - name: Build package distributions + run: make build + + - uses: actions/upload-artifact@v4 + with: + path: ./dist + + # https://docs.pypi.org/trusted-publishers/using-a-publisher/ + pypi-publish: + needs: ['build'] + environment: 'publish' + + name: upload release to PyPI + runs-on: ubuntu-latest + permissions: + # Mandatory for trusted publishing + id-token: write + steps: + - uses: actions/download-artifact@v4 + + - name: Publish package distributions to PyPI + uses: pypa/gh-action-pypi-publish@release/v1 + with: + packages-dir: artifact/ + print-hash: true From da43990ae1f76b53cd42f93878e1db549adb5c29 Mon Sep 17 00:00:00 2001 From: "Storm B. Heg" Date: Thu, 7 Mar 2024 17:56:58 +0100 Subject: [PATCH 12/20] Add back twine check --- Makefile | 1 + 1 file changed, 1 insertion(+) diff --git a/Makefile b/Makefile index 48b65d83..e090dfd2 100644 --- a/Makefile +++ b/Makefile @@ -63,6 +63,7 @@ install-python: ##- Install Python modules .PHONY: build build: clean frontend-dist ##- Build Sphinx extension python -m build + twine check dist/* ls -l dist From 7391e40744348b79b4bfd7ccaee918ddd4fd9fb6 Mon Sep 17 00:00:00 2001 From: "Storm B. Heg" Date: Thu, 7 Mar 2024 17:57:17 +0100 Subject: [PATCH 13/20] Drop unnecessary dependencies zest-releaser is sort of useful, but we don't use it much for other repositories and is thus unfamiliar to most. --- requirements-dev.txt | 3 --- 1 file changed, 3 deletions(-) diff --git a/requirements-dev.txt b/requirements-dev.txt index 1b880c8f..c5352f90 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -6,9 +6,6 @@ build docutils flake8 percy-selenium -pip pytest selenium -setuptools twine -zest.releaser From 117f1562fa78d66e66da254ec2c085a90f85bc90 Mon Sep 17 00:00:00 2001 From: "Storm B. Heg" Date: Thu, 7 Mar 2024 17:59:05 +0100 Subject: [PATCH 14/20] Update release instructions --- README.md | 31 ++++++++----------------------- 1 file changed, 8 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 4dcbb686..277b39a1 100644 --- a/README.md +++ b/README.md @@ -40,31 +40,16 @@ html_theme = 'sphinx_wagtail_theme' ### Release process -Checklist: +This section is for maintainer reference. -- [ ] `CONTRIBUTORS.md` is updated -- [ ] `CHANGELOG.md` is updated -- [ ] `setup.cfg` is updated (see `version`) -- [ ] Everything is committed, clean checkout -- [ ] `~/.pypirc` has a username and password (token) -- [ ] Add a git tag at the release commit with the format `X.Y.Z` -- [ ] Create a GitHub release against that tag with the title format `vX.Y.Z` +1. Check all relevant changes since the last release are documented in `CHANGELOG.md` +2. Check if there are any new contributors and add them to `CONTRIBUTORS.md` +3. Update the version number in `setup.cfg`. The version number should follow [Semantic Versioning](https://semver.org/). +4. Commit and push the changes +5. Create and push a new tag with the version number, prefixed with `v`. For example, `v1.2.3` +6. In the GitHub repository, create a new release against the tag you just pushed. +7. Once the release is created, the CI will automatically publish the new version to PyPI. -With an active virtual environment: - -```sh -python -m pip install --upgrade -r requirements.txt -make clean -make clean-frontend -npm ci -npm run build -prerelease -git tag -a N.N.N -m "N.N.N" -git push origin N.N.N -python -m build -python -m twine upload --repository pypi dist/* -postrelease -``` ## Credits From 05d1742f7b60c5594920e94af4b960b4f0d3b8e2 Mon Sep 17 00:00:00 2001 From: "Storm B. Heg" Date: Thu, 7 Mar 2024 18:09:16 +0100 Subject: [PATCH 15/20] Install Black, add make format command --- Makefile | 16 +++++++++++++++- requirements-dev.txt | 1 + 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index e090dfd2..c5c9fc72 100644 --- a/Makefile +++ b/Makefile @@ -132,7 +132,6 @@ watch: npm run watch - .PHONY: watchdocs watchdocs: docs ##- Redo 'docs' and watch for changes (=make sd) pip install watchdog @@ -145,6 +144,7 @@ lint: lint-python lint-frontend ##- Run all linters .PHONY: lint-python lint-python: + black --check sphinx_wagtail_theme docs/ tests/ flake8 *.py flake8 sphinx_wagtail_theme flake8 tests @@ -155,6 +155,20 @@ lint-frontend: npm run lint +.PHONY: format +format: format-python format-frontend ##- Run all formatters + + +.PHONY: format-python +format-python: + black sphinx_wagtail_theme docs/ tests/ + + +.PHONY: format-frontend +format-frontend: + npm run format + + .PHONY: test test: pytest diff --git a/requirements-dev.txt b/requirements-dev.txt index c5352f90..adbf0f1b 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -5,6 +5,7 @@ build docutils flake8 +black>=24,<=25 percy-selenium pytest selenium From a097b909e1ed52ce112b452129ecb5d2f6c8e2e8 Mon Sep 17 00:00:00 2001 From: "Storm B. Heg" Date: Thu, 7 Mar 2024 18:09:50 +0100 Subject: [PATCH 16/20] Reformat with Black 2024 stable style --- README.md | 1 - docs/conf.py | 72 +++++++++++++++++++------------- sphinx_wagtail_theme/__init__.py | 8 ++-- tests/test_visual_regression.py | 2 +- 4 files changed, 47 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 277b39a1..4a0e09a6 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,6 @@ This section is for maintainer reference. 6. In the GitHub repository, create a new release against the tag you just pushed. 7. Once the release is created, the CI will automatically publish the new version to PyPI. - ## Credits [Sphinx Wagtail theme](https://github.com/wagtail/sphinx_wagtail_theme) is based on [Sphinx Typo3 theme](https://github.com/TYPO3-Documentation/sphinx_typo3_theme) which is based on [t3SphinxThemeRtd](https://github.com/typo3-documentation/t3SphinxThemeRtd) which is based on the [Read the Docs Sphinx theme](https://github.com/readthedocs/sphinx_rtd_theme). diff --git a/docs/conf.py b/docs/conf.py index 55e1a055..830a305e 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -3,23 +3,23 @@ import sphinx_wagtail_theme -sys.path.insert(0, os.path.abspath('..')) +sys.path.insert(0, os.path.abspath("..")) extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.viewcode', - 'sphinx_wagtail_theme', - 'myst_parser', - 'sphinx_copybutton', + "sphinx.ext.autodoc", + "sphinx.ext.viewcode", + "sphinx_wagtail_theme", + "myst_parser", + "sphinx_copybutton", ] -templates_path = ['_templates'] +templates_path = ["_templates"] source_suffix = { - '.rst': 'restructuredtext', - '.txt': 'markdown', - '.md': 'markdown', + ".rst": "restructuredtext", + ".txt": "markdown", + ".md": "markdown", } -master_doc = 'index' -project = 'Sphinx Wagtail theme' +master_doc = "index" +project = "Sphinx Wagtail theme" copyright = "2022, Wagtail contributors" author = "Wagtail" # The short X.Y version. @@ -27,41 +27,53 @@ # The full version, including alpha/beta/rc tags. release = sphinx_wagtail_theme.__version__ language = "en" -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'requirements.txt'] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "requirements.txt"] # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False -today_fmt = '%Y-%m-%d %H:%M' +today_fmt = "%Y-%m-%d %H:%M" # -- Options for HTML output ------------------------------------------- -html_theme = 'sphinx_wagtail_theme' +html_theme = "sphinx_wagtail_theme" html_static_path = [] -html_favicon = 'favicon.ico' +html_favicon = "favicon.ico" # -- Options for HTMLHelp output --------------------------------------- -htmlhelp_basename = 'sphinx_wagtail_themedoc' +htmlhelp_basename = "sphinx_wagtail_themedoc" # -- Options for LaTeX output ------------------------------------------ latex_elements = {} latex_documents = [ - (master_doc, 'sphinx_wagtail_theme.tex', - 'Sphinx Wagtail theme documentation', - 'Martin Bless', 'manual'), + ( + master_doc, + "sphinx_wagtail_theme.tex", + "Sphinx Wagtail theme documentation", + "Martin Bless", + "manual", + ), ] # -- Options for manual page output ------------------------------------ man_pages = [ - (master_doc, 'sphinx_wagtail_theme', - 'Sphinx Wagtail theme documentation', - [author], 1) + ( + master_doc, + "sphinx_wagtail_theme", + "Sphinx Wagtail theme documentation", + [author], + 1, + ) ] # -- Options for Texinfo output ---------------------------------------- texinfo_documents = [ - (master_doc, 'sphinx_wagtail_theme', - 'Sphinx Wagtail theme documentation', - author, - 'sphinx_wagtail_theme', - 'One line description of project.', - 'Miscellaneous'), + ( + master_doc, + "sphinx_wagtail_theme", + "Sphinx Wagtail theme documentation", + author, + "sphinx_wagtail_theme", + "One line description of project.", + "Miscellaneous", + ), ] -github_doc_root = 'https://github.com/wagtail/sphinx_wagtail_theme/tree/main/docs' +github_doc_root = "https://github.com/wagtail/sphinx_wagtail_theme/tree/main/docs" + def setup(app): pass diff --git a/sphinx_wagtail_theme/__init__.py b/sphinx_wagtail_theme/__init__.py index 1b2319bf..5e21ca8b 100644 --- a/sphinx_wagtail_theme/__init__.py +++ b/sphinx_wagtail_theme/__init__.py @@ -33,14 +33,14 @@ def update_context(app, pagename, templatename, context, doctree): `page.html`. """ - context['theme_version'] = __version__ - return app.builder.env.metadata.get(pagename, {}).get('template') + context["theme_version"] = __version__ + return app.builder.env.metadata.get(pagename, {}).get("template") def setup(app): """Setup functionality called by Sphinx""" - app.connect('html-page-context', update_context) - if hasattr(app, 'add_html_theme'): + app.connect("html-page-context", update_context) + if hasattr(app, "add_html_theme"): theme_path = os.path.abspath(os.path.dirname(__file__)) app.add_html_theme("sphinx_wagtail_theme", theme_path) # unconfirmed: just assuming that parallel_write_safe is ok diff --git a/tests/test_visual_regression.py b/tests/test_visual_regression.py index dea22e6a..24b17a79 100644 --- a/tests/test_visual_regression.py +++ b/tests/test_visual_regression.py @@ -25,7 +25,7 @@ def main(): exit(1) handler_class = DocsHTTPRequestHandler - server_address = ('127.0.0.1', 8000) + server_address = ("127.0.0.1", 8000) httpd = server.HTTPServer(server_address, handler_class) From 953c9db2b8b77e1313fa235d58a3c4a4960c2aa5 Mon Sep 17 00:00:00 2001 From: "Storm B. Heg" Date: Thu, 7 Mar 2024 18:36:07 +0100 Subject: [PATCH 17/20] Update RTD config --- .readthedocs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 7c1559d5..9863b229 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -10,7 +10,7 @@ build: nodejs: '20' jobs: post_install: - - make setup-frontend + - make install-frontend pre_build: - make frontend From 1ca6e374a0d6059aa50b42530fac669ae3cee13a Mon Sep 17 00:00:00 2001 From: "Storm B. Heg" Date: Wed, 20 Mar 2024 11:25:40 +0100 Subject: [PATCH 18/20] Remove vercel preview environment We are now using ReadTheDocs for this exclusively. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4a0e09a6..abcd8553 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# [Sphinx Wagtail theme](https://sphinx-wagtail-theme.vercel.app/) +# [Sphinx Wagtail theme](https://sphinx-wagtail-theme.readthedocs.io/) [![CI status](https://github.com/wagtail/sphinx_wagtail_theme/workflows/CI/badge.svg)](https://github.com/wagtail/sphinx_wagtail_theme/actions?query=workflow%3ACI) [![PyPI version](https://badge.fury.io/py/sphinx-wagtail-theme.svg)](https://badge.fury.io/py/sphinx-wagtail-theme) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) From e8d0548acd15bf5da41d10a253450c45f398efee Mon Sep 17 00:00:00 2001 From: Sage Abdullah Date: Wed, 25 Sep 2024 17:13:41 -0400 Subject: [PATCH 19/20] Add changelog --- CHANGELOG.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5239e420..20040f60 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,10 +7,11 @@ All notable changes to this project will be documented in this file. ### Added - Use new Wagtail logo variant for favicon and other logos (Osaf AliSayed) +- Set up GitHub Actions for publishing new releases using PyPI's trusted publishing (Storm Heg) ### Changed -- ... +- Clean up development and release instructions and format codebase with Black (Storm Heg) ### Removed From 78994a4f1c6c39b986713ca3e762211b15509805 Mon Sep 17 00:00:00 2001 From: "Storm B. Heg" Date: Thu, 26 Sep 2024 21:17:03 -0400 Subject: [PATCH 20/20] Consolidate frontend and python CI job into one --- .github/workflows/ci.yml | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 61dff018..2ab8a739 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -7,7 +7,7 @@ on: pull_request: jobs: - frontend_qa: + qa: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 @@ -15,22 +15,19 @@ jobs: with: node-version: '20' cache: 'npm' - - run: npm ci - - run: make lint-frontend - - run: make frontend - - python_qa: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: '3.12' + cache: 'pip' + - run: npm ci + - run: make lint-frontend + - run: make frontend - run: make install-python - run: make lint-python - run: make test visual-regression-tests: + needs: qa runs-on: ubuntu-latest env: PERCY_TOKEN: ${{ secrets.PERCY_TOKEN }}