Table of contents

[henryiii]

Most tools have a way to tell the user that they can do. For example:

nox:

$ nox -l
Sessions defined in /Users/henryschreiner/git/scikit-build/scikit-build-core/noxfile.py:

* lint -> Run the linter.
* pylint -> Run PyLint.
* generate_schema -> (Re)generate src/scikit_build_core/resources/scikit-build.schema.json from model.
* tests -> Run the unit and regular tests. Includes coverage if --cov passed.
* readme -> Update the readme with cog. Pass --check to check instead.
- minimums -> Test the minimum versions of dependencies.
- docs -> Build the docs. Use "--non-interactive" to avoid serving. Pass "-b linkcheck" to check links.
* build_api_docs -> Build (regenerate) API docs.
- build -> Build an SDist and wheel.
* test_doc_examples(getting_started/c)
* test_doc_examples(getting_started/abi3)
* test_doc_examples(getting_started/pybind11)
* test_doc_examples(getting_started/nanobind)
* test_doc_examples(getting_started/swig)
* test_doc_examples(getting_started/cython)
* test_doc_examples(getting_started/fortran)
* test_doc_examples(downstream/pybind11_example)
* test_doc_examples(downstream/nanobind_example)
- downstream -> Build a downstream project.
- vendor_pyproject_metadata -> Vendor pyproject.toml metadata.

sessions marked with * are selected, sessions marked with - are skipped.

(It's also color coded in the terminal)

tox:

$ tox -l
type
docs
path
py312
py312-min
py311
py311-min
py310
py310-min
py39
py39-min
py38
py38-min
pypy310
pypy310-min
pypy39
pypy39-min
pypy38
pypy38-min

Or -lv or

$ tox -av
.pkg: find interpreter for spec PythonSpec(path=/usr/local/Cellar/tox/4.15.0/libexec/bin/python)
.pkg: proposed PythonInfo(spec=CPython3.12.3.final.0-64, system=/usr/local/opt/python@3.12/bin/python3.12, exe=/usr/local/Cellar/tox/4.15.0/libexec/bin/python, platform=darwin, version='3.12.3 (main, Apr  9 2024, 08:09:14) [Clang 15.0.0 (clang-1500.3.9.4)]', encoding_fs_io=utf-8-utf-8)
.pkg: find interpreter for spec PythonSpec(path=/usr/local/Cellar/tox/4.15.0/libexec/bin/python)
.pkg: proposed PythonInfo(spec=CPython3.12.3.final.0-64, system=/usr/local/opt/python@3.12/bin/python3.12, exe=/usr/local/Cellar/tox/4.15.0/libexec/bin/python, platform=darwin, version='3.12.3 (main, Apr  9 2024, 08:09:14) [Clang 15.0.0 (clang-1500.3.9.4)]', encoding_fs_io=utf-8-utf-8)
default environments:
fix         -> run static analysis and style checks
type        -> run type check on code base
docs        -> build documentations
path        -> verify build can run from source (bootstrap)
py312       -> run test suite with py312
py312-min   -> check minimum versions required of all dependencies
py311       -> run test suite with py311
py311-min   -> check minimum versions required of all dependencies
py310       -> run test suite with py310
py310-min   -> check minimum versions required of all dependencies
py39        -> run test suite with py39
py39-min    -> check minimum versions required of all dependencies
py38        -> run test suite with py38
py38-min    -> check minimum versions required of all dependencies
pypy310     -> run test suite with pypy310
pypy310-min -> check minimum versions required of all dependencies
pypy39      -> run test suite with pypy39
pypy39-min  -> check minimum versions required of all dependencies
pypy38      -> run test suite with pypy38
pypy38-min  -> check minimum versions required of all dependencies

additional environments:
dev         -> generate a DEV environment
coverage    -> combine coverage from test environments
bump        -> bump versions, pass major/minor/patch

pixi:

$ pixi task list
* book
* lab
* pdf

I think this is very useful when sitting down at a new project (or at one you've not looked at for a few months/weeks/days/hours...) to see exactly what you can do. I think it's really a "table of contents" of sorts, not necessarily just a list of tasks. If a project supports hatch fmt or hatch test, I think it would be nice if they could surface that support here. There should also be a way to support PEP 723 scripts, as well. They also need a way to add descriptions (PEP 723 could come from the first line of the docstring! Or an inline tool.hatch table.). Hatch already has several things that are somewhat similar:

• hatch env show: this is pretty close, though there's no way to add descriptions or show support for other supported features.
• hatch by itself prints help which includes things like test (regardless of whether those are supported), but nothing user defined. In fact, it's just like hatch --help except it's entirely bold for some reason.

My suggestion would be to add a hatch toc command, and maybe have hatch display the toc. It's very important that it's discoverable - maybe -l (which is pretty common) is better just because people know to try it?

I think the display could then show all items defined or with a description added by the user:

$ hatch toc
Useful Hatch commands:
  build          Build a project
  test           Run tests
  fmt            Format and lint source code
  run lint:lint  Lint the project with pre-commit
  run pylint:pylint
                 Run pylint on the project
  run tools/sync.py
                 Sync with schema-store

This could be configured something like this (very rough draft):

[tool.hatch.toc]
default = ["build", "test", "fmt"]
inline-scripts = ["tools/sync.py"]
envs.lint.scripts.lint = "Lint the project with pre-commit"
envs.pylint.scripts.pylint = "Run pylint on the project"

As a package author, I'd err more on allowing me to configure a nice experience for users (people using hatch on my package). If I haven't verified something works yet, I'd rather it not show up in this "what can I do" listing. Though maybe anything that is configured could automatically show up (like if someone sets tool.hatch.envs.hatch-test, then it's safe to show test by default)? I think it is important it show something somewhat useful if it's not configured, so people know to look for it on new projects.

Duplicate of #1074 and #1035 to some extent.

Thoughts? Very much a rough sketch of what might be nice, not a concrete proposal.