diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index aa874279..78484a86 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -15,18 +15,38 @@ Nox is pre-installed in the Codespaces environment. So, after activating a Codes you can just open the terminal and run `nox` to run all the checks and tests. ## Local -If you don't have nox, you can use `pipx run nox` to run it without installing, or `pipx install nox`. If you don't have `pipx` (`pip` for applications), then you can install with with `pip install pipx` (the only case were installing an application with regular pip is reasonable). If you use macOS, then `pipx` and `nox` are both in brew, use `brew install pipx nox`. + +If you don't have nox, you can do the following to install `nox`: + +```bash +pip install nox +``` + +If you use macOS, then `nox` is in brew: + +```bash +brew install nox +``` ## Nox basics +### What is it? + +`nox` is a command-line tool that automates testing in multiple Python environments, +similar to tox. Unlike tox, +Nox uses a standard Python file for configuration, +you can find this configuration in [`noxfile.py`](../noxfile.py). + +### How do I use it? + To use, run `nox`. This will lint and test using every installed version of Python on your system, skipping ones that are not installed. You can also run specific jobs: -```console -$ nox -s lint # Lint only -$ nox -s tests # Python tests -$ nox -s build # Make an SDist and wheel +```bash +nox -s lint # Lint only +nox -s tests # Python tests +nox -s build # Make an SDist and wheel ``` Nox handles everything for you, including setting up a temporary virtual diff --git a/noxfile.py b/noxfile.py index 4b523174..5dc68404 100644 --- a/noxfile.py +++ b/noxfile.py @@ -8,7 +8,7 @@ DIR = Path(__file__).parent.resolve() -nox.options.sessions = ["lint", "pylint", "tests"] +nox.options.sessions = ["lint", "pylint", "tests", "build"] @nox.session @@ -40,68 +40,6 @@ def tests(session: nox.Session) -> None: session.run("pytest", *session.posargs) -@nox.session -def docs(session: nox.Session) -> None: - """ - Build the docs. Pass "--serve" to serve. - """ - - parser = argparse.ArgumentParser() - parser.add_argument("--serve", action="store_true", help="Serve after building") - parser.add_argument( - "-b", dest="builder", default="html", help="Build target (default: html)" - ) - args, posargs = parser.parse_known_args(session.posargs) - - if args.builder != "html" and args.serve: - session.error("Must not specify non-HTML builder with --serve") - - session.install(".[docs]") - session.chdir("docs") - - if args.builder == "linkcheck": - session.run( - "sphinx-build", "-b", "linkcheck", ".", "_build/linkcheck", *posargs - ) - return - - session.run( - "sphinx-build", - "-n", # nitpicky mode - "-T", # full tracebacks - "-W", # Warnings as errors - "--keep-going", # See all errors - "-b", - args.builder, - ".", - f"_build/{args.builder}", - *posargs, - ) - - if args.serve: - session.log("Launching docs at http://localhost:8000/ - use Ctrl-C to quit") - session.run("python", "-m", "http.server", "8000", "-d", "_build/html") - - -@nox.session -def build_api_docs(session: nox.Session) -> None: - """ - Build (regenerate) API docs. - """ - - session.install("sphinx") - session.chdir("docs") - session.run( - "sphinx-apidoc", - "-o", - "api/", - "--module-first", - "--no-toc", - "--force", - "../src/braingeneers", - ) - - @nox.session def build(session: nox.Session) -> None: """