update so we can install from git url, and move scripts dir too

Author: bitplane

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.3.0
+    rev: v5.0.0
     hooks:
     -   id: check-toml
     -   id: check-symlinks
@@ -10,26 +10,26 @@ repos:
     -   id: mixed-line-ending
     -   id: trailing-whitespace
 -   repo: https://github.com/psf/black
-    rev: 22.10.0
+    rev: 24.10.0
     hooks:
     -   id: black
 -   repo: https://github.com/PyCQA/isort
-    rev: 5.10.1
+    rev: 5.13.2
     hooks:
     -   id: isort
 -   repo: https://github.com/PyCQA/flake8
-    rev: 5.0.4
+    rev: 7.1.1
     hooks:
     -   id: flake8
 -   repo: https://github.com/shellcheck-py/shellcheck-py
-    rev: v0.8.0.4
+    rev: v0.10.0.1
     hooks:
     -   id: shellcheck
 -   repo: https://github.com/jackdewinter/pymarkdown
-    rev: v0.9.8
+    rev: v0.9.25
     hooks:
     -   id: pymarkdown
 -   repo: https://github.com/cmake-lint/cmake-lint
-    rev: 1.4.2
+    rev: 1.4.3
     hooks:
     -   id: cmakelint

.vscode/extensions.json

@@ -1,6 +1,8 @@
 {
 	"recommendations": [
 		"ms-python.python",
-		"davidanson.vscode-markdownlint"
+		"davidanson.vscode-markdownlint",
+		"ms-vscode.makefile-tools",
+		"ms-python.flake8"
 	]
 }

.vscode/settings.json

@@ -5,6 +5,11 @@
     "python.linting.enabled": true,
     "python.testing.pytestEnabled": true,
     "python.testing.unittestEnabled": false,
-    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python3",
-    "python.envFile": "${workspaceFolder}/.env"
+    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+    "python.analysis.extraPaths": ["${workspaceFolder}/merge-files/src"],
+    "python.envFile": "${workspaceFolder}/.env",
+    "[python]": {
+        "editor.defaultFormatter": "ms-python.black-formatter"
+    },
+    "python.formatting.provider": "none"
 }

LICENSE.txt LICENSE.mdLICENSE.txt renamed to LICENSE.md

@@ -1,3 +1,5 @@
+# WTFPL + Warranty
+
 Licensed under the WTFPL with one additional clause:
 
 1. Don't blame me.

Makefile

@@ -3,41 +3,53 @@
 		pre-commit update-pre-commit
 
 
-all: dev coverage ## builds everything
+PROJECT_NAME := example_package
 
-install: .venv/.installed ## installs the venv and the project packages
 
-dev: .venv/.installed-dev pre-commit ## prepare local repo and venv for dev
+all: dev coverage  ## builds everything
+
+install: .venv/.installed  ## installs the venv and the project packages
+
+dev: .venv/.installed-dev pre-commit  ## prepare local repo and venv for dev
 
 test: .venv/.installed-dev  ## run the project's tests
-	build/test.sh
+	scripts/test.sh $(PROJECT_NAME)
 
-coverage: .venv/.installed-dev build/coverage.sh  ## build the html coverage report
-	build/coverage.sh
+coverage: .venv/.installed-dev scripts/coverage.sh  ## build the html coverage report
+	scripts/coverage.sh $(PROJECT_NAME)
+
+docs: .docs/index.html ## build the documentation
 
 clean:  ## delete caches and the venv
-	build/clean.sh
+	scripts/clean.sh
 
-pre-commit: .git/hooks/pre-commit ## install pre-commit into the git repo
+pre-commit: .git/hooks/pre-commit  ## install pre-commit into the git repo
 
-update-pre-commit: build/update-pre-commit.sh ## autoupdate pre-commit
-	build/update-pre-commit.sh
+update-pre-commit: scripts/update-pre-commit.sh  ## autoupdate pre-commit
+	scripts/update-pre-commit.sh
 
+dist: scripts/dist.sh ## build the distributable files
+	scripts/dist.sh $(PROJECT_NAME)
 
+release: scripts/release.sh ## publish to pypi
+	scripts/release.sh $(PROJECT_NAME)
 
 # Caching doesn't work if we depend on PHONY targets
 
-.venv/.installed: */pyproject.toml .venv/bin/activate build/install.sh
-	build/install.sh
+.docs/index.html: .venv/.installed-dev scripts/docs.sh mkdocs.yml $(shell find -name '*.md')
+	scripts/docs.sh $(PROJECT_NAME)
+
+.venv/.installed: pyproject.toml .venv/bin/activate scripts/install.sh $(shell find src -name '*.py')
+	scripts/install.sh $(PROJECT_NAME)
 
-.venv/.installed-dev: */pyproject.toml .venv/bin/activate build/install-dev.sh
-	build/install-dev.sh
+.venv/.installed-dev: pyproject.toml .venv/bin/activate scripts/install-dev.sh
+	scripts/install-dev.sh $(PROJECT_NAME)
 
 .venv/bin/activate:
-	build/venv.sh
+	scripts/venv.sh
 
-.git/hooks/pre-commit: build/install-pre-commit.sh
-	build/install-pre-commit.sh
+.git/hooks/pre-commit: scripts/install-pre-commit.sh
+	scripts/install-pre-commit.sh
 
 
 help: ## Show this help

README.md

@@ -24,7 +24,7 @@ The trick is:
 
 1. Have each step run one script that has a good name, so they're documented
    by that script and its name, and can be run without `make` - like from
-   your editor or whatever. I keep mine in `./build/`. The reason for having
+   your editor or whatever. I keep mine in `./scripts/`. The reason for having
    them as separate scripts is because you might want to bypass dependencies
    in a CI pipeline.
 2. Have the dependencies for the step be the script itself plus one file
@@ -47,9 +47,15 @@ I like `flake8` for linting because it's not as harsh as `pylint`, and is
 supported by my IDE of choice.
 
 Part of the `make dev` setup installs `pre-commit`, which will make sure that
-commits are up to a certain standard. The provided config file runs code
+commits are up to a certain standard. The provided config file runs the code
 formatters, linters and a few other checks. Have a look at
-`.pre-commit-config.yaml` to see what's going on in there.
+`.pre-commit-config.yaml` to see what's going on in there. pre-commit is very
+slow and very annoying, but it forces code quality on us which makes up for the
+inconvenience.
+
+See the `.flake8` config for some ignored rules where flake8 and black get into
+a fight, and there's `isort` and `black` conflict rules in the pre-commit
+config too.
 
 ### IDE
 
@@ -62,6 +68,9 @@ belong to the project, so it's appropriate to put them in source control.
 The config also provides recommendations for extensions, which you'll be
 prompted to install when you open the project for the first time.
 
+I could (and sometimes do) go one step further and use devcontainers, but at
+time of writing it's still a bit fiddly to get set up.
+
 ### Package layout
 
 Under the `example_package` dir there's a `pyproject.toml` that defines the
@@ -71,19 +80,43 @@ the code and tests.
 The layout is as-per the pypi packaging guidelines. When referencing stuff in
 the code I tend to use the full `package.module` names because otherwise imports
 tend to break in weird ways in different environments, and it means I can
-reference stuff in parent directories without ripping my hair out.
+reference stuff in parent directories without ripping my hair out. It makes the
+imports look a bit Java-y but it's staying that way until implicit imports are
+removed from Python.
 
 ### Testing
 
-I use `pytest` and write tests in a functional style, and develop using TDD.
-If you get into the habit of actually running a new piece of code from a new
-unit test then you'll find yourself writing testable code. Tests are
+I use `pytest` and write tests in a functional style, and develop largely using
+TDD. If you get into the habit of actually running a new piece of code from a
+new unit test then you'll find yourself writing testable code. Tests are
 fundamentally just other pieces of code, so if a function is difficult to test
-then it's probably difficult to reuse too.
+then it's probably difficult to reuse too. But it doesn't work all the time;
+testing filesystem interactions and external services have a heavy
+test-development overhead, which hinders rather than helps refactoring efforts;
+your mileage may vary.
+
+Run `make coverage` for a test coverage report.
+
+### CI and CD
+
+There's a couple of workflows in the `.github` dir, one to run the unit tests
+and one to release the project to pypi. The first
+
+The release process runs whenever you
+push tag changes to GitHub.
+
+Before the release process will work you
+need to get a key from pypi and add
+
+there's a couple of workflows, one that runs the
+`make test` any time a commit is pushed. This
+
+### Documentation
 
-Run `make coverage` for a test coverage report. I like to keep my coverage at
-100%. Not sure if that's a taste thing or a side-effect of the way I'm
-developing, but I like it.
+You'll see a `mkdocs` config in the root. This is combined with the `make docs`
+script to make the github pages documentation for the project. If you look at
+this README.md file you'll see it's actually a symlink to the one in the package
+dir, and it's also symlinked from
 
 ## Some opinionated stuff
 

build/clean.sh

@@ -13,7 +13,8 @@ dev = [
     "flake8",
     "pre-commit",
     "pytest",
-    "coverage"
+    "coverage",
+    "pytest-cov"
 ]
 
 [build-system]

example_package/pyproject.toml pyproject.tomlexample_package/pyproject.toml renamed to pyproject.toml

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+rm -r .venv                                         2>/dev/null
+rm .coverage                                        2>/dev/null
+rm -r htmlcov                                       2>/dev/null
+rm .git/hooks/pre-commit                            2>/dev/null
+find . -name '__pycache__' -exec rm -rv {} \;       2>/dev/null
+find . -name '*.egg-info' -exec rm -rv {} \;        2>/dev/null
+find . -name '.pytest_cache' -exec rm -rv {} \;     2>/dev/null
+rm ./*/dist -r                                      2>/dev/null
+
+echo Cleaned project

scripts/clean.sh

@@ -2,5 +2,4 @@
 
 source .venv/bin/activate
 
-coverage run -m pytest ./*/tests
-coverage html
+pytest --cov="src/$1" --cov-report=html .