From f17c6c2002ee6a622f3882895897cf8fad82a897 Mon Sep 17 00:00:00 2001 From: adigitoleo Date: Fri, 23 Aug 2024 17:28:45 +1000 Subject: [PATCH] dev: Migrate from Makefile to justfile The [just](https://github.com/casey/just) build command runner is "just" a better `make`, for our purposes. In particular, it properly terminates the documentation build if `setuptools-scm` is not installed. I'm sure there is a way to cast spells at `make` to make it do that, but why? Whenever there's a big .PHONY line in a Makefile, it means that `make` is probably the wrong tool. Also, the old Makefile I provided was only valid for GNU make (make portability is a bit gross). Also, `just` has binaries built for every major platform so installing is not a hassle. --- Makefile | 39 --------------------------------------- README.md | 6 ++++-- justfile | 33 +++++++++++++++++++++++++++++++++ tests/README.md | 3 ++- 4 files changed, 39 insertions(+), 42 deletions(-) delete mode 100644 Makefile create mode 100644 justfile diff --git a/Makefile b/Makefile deleted file mode 100644 index 471c91a1..00000000 --- a/Makefile +++ /dev/null @@ -1,39 +0,0 @@ -.SHELLFLAGS += -u -.ONESHELL: -MAKEFLAGS += --no-builtin-rules -VERSION = $(shell python -m setuptools_scm -f plain) - -# NOTE: Keep this at the top! Bare `make` should just build the sdist + bdist. -dist: - python -m build - -release: dist - python -m twine upload dist/* - -test: - mkdir out - pytest -v --outdir=out - -# WARNING: --math fetches .js code from a CDN, be careful where it comes from: -# https://github.com/mitmproxy/pdoc/security/advisories/GHSA-5vgj-ggm4-fg62 -html: - 2>pdoc.log pdoc -t docs/template -o html pydrex !pydrex.mesh !pydrex.distributed tests \ - --favicon "https://raw.githubusercontent.com/seismic-anisotropy/PyDRex/main/docs/assets/favicon32.png" \ - --footer-text "PyDRex $(VERSION)" \ - --math - -# WARNING: --math fetches .js code from a CDN, be careful where it comes from: -# https://github.com/mitmproxy/pdoc/security/advisories/GHSA-5vgj-ggm4-fg62 -live_docs: - pdoc -t docs/template pydrex !pydrex.mesh !pydrex.distributed tests \ - --favicon "https://raw.githubusercontent.com/seismic-anisotropy/PyDRex/main/docs/assets/favicon32.png" \ - --footer-text "PyDRex $(VERSION)" \ - --math - -clean: - rm -rf dist - rm -rf out - rm -rf html - rm -rf pdoc.log - -.PHONY: release test live_docs clean diff --git a/README.md b/README.md index 08e3914e..17f76953 100644 --- a/README.md +++ b/README.md @@ -59,11 +59,13 @@ They have their own README file as well. The documentation can be built offline from a git clone or unpacked source distribution. Install documentation builder dependencies with `pip install '.[doc]'`. +Developers are also recommended to download the [just](https://github.com/casey/just) command runner. +Otherwise, build commands can be found in the provided `justfile`. -Run `make html` from the terminal to generate PyDRex's documentation +Run `just html` from the terminal to generate PyDRex's documentation (available in the `html` directory), including the API reference. The homepage will be `html/index.html`. -Alternatively, run `make live_docs` to build and serve the documentation on a `localhost` port. +Alternatively, run `just live_docs` to build and serve the documentation on a `localhost` port. Follow the displayed prompts to open the live documentation in a browser. It should automatically reload after changes to the source code. diff --git a/justfile b/justfile new file mode 100644 index 00000000..3a2f12cb --- /dev/null +++ b/justfile @@ -0,0 +1,33 @@ +VERSION := `python -m setuptools_scm -f plain` + +build: + python -m build + +release: build + python -m twine upload dist/* + +test: + mkdir out + pytest -v --outdir=out + +html: + # WARNING: --math fetches .js code from a CDN, be careful where it comes from: + # https://github.com/mitmproxy/pdoc/security/advisories/GHSA-5vgj-ggm4-fg62 + 2>pdoc.log pdoc -t docs/template -o html pydrex !pydrex.mesh !pydrex.distributed tests \ + --favicon "https://raw.githubusercontent.com/seismic-anisotropy/PyDRex/main/docs/assets/favicon32.png" \ + --footer-text "PyDRex {{VERSION}}" \ + --math + +live_docs: + # WARNING: --math fetches .js code from a CDN, be careful where it comes from: + # https://github.com/mitmproxy/pdoc/security/advisories/GHSA-5vgj-ggm4-fg62 + pdoc -t docs/template pydrex !pydrex.mesh !pydrex.distributed tests \ + --favicon "https://raw.githubusercontent.com/seismic-anisotropy/PyDRex/main/docs/assets/favicon32.png" \ + --footer-text "PyDRex {{VERSION}}" \ + --math + +clean: + rm -rf dist + rm -rf out + rm -rf html + rm -rf pdoc.log diff --git a/tests/README.md b/tests/README.md index ea0e8e76..ab0d68f8 100644 --- a/tests/README.md +++ b/tests/README.md @@ -1,7 +1,8 @@ # PyDRex tests Running the base test suite requires [pytest](https://docs.pytest.org) and up to ~16GB RAM. -By default, `make test` will attempt to write persistent logs and output to `./out/`. +If the [just](https://github.com/casey/just) command runner is installed, +`just test` will run the test suite and attempt to write persistent logs and output to `./out/`. Alternatively, run `pytest` from the root of the source tree. To print more verbose test progress and information, use the flag `pytest -v`.