Improve beginner friendliness of output from ./make.py format

[pushfoo]

trafficstars

Enhancement

CI formatting output could be clearer for beginners.

Actual behavior:

Expected behavior:

Useful debug output

Steps to reproduce/example code:

PR something or run ./make.py format --check

[Cleptomania]

What else would you want it to say? It shows the problematic file.

You’re not meant to go reformat it by hand, it’s meant to run make.py format and it will fix it with the auto formatter.

[pushfoo]

I think it should suggest the following:

1. running ./make.py format locally
2. git diff to highlight changes

The current output is confusing because the following aren't clear:

• whether ruff or black is the active formatter
• what the next steps to begin fixing the formatting issue are

[pushfoo]

Making those next steps clear matters because running ruff format changed a few hundred lines for me.

I reverted since I remembered we're using black + config tweaks this project, but beginners will get confused.

[cdeil]

@pushfoo and all - I took a stab at this in #2550

One further suggestion I have is to delete all or most "Docs Extra Formats" from make.py. Having so much stuff is confusing for newcomers like me, and is anyone actually using them? I think this is just generating short sphinx commands that are very rarely used? Centralizing config to pyproject.toml and avoiding extra config like all the variables in make.py related to sphinx build I think would be nice - assuming all dev/maintainer needs/requirements can be met.

Also ruff is so fast and consistent that I think we could simply run ruff format including the import sorting and get rid of the multiple commands there?

% ./make.py --help
                                                                                                            
 Usage: make.py [OPTIONS] COMMAND [ARGS]...                                                                 
                                                                                                            
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --install-completion          Install completion for the current shell.                                  │
│ --show-completion             Show completion for the current shell, to copy it or customize the         │
│                               installation.                                                              │
│ --help                        Show this message and exit.                                                │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Docs Extra Formats ─────────────────────────────────────────────────────────────────────────────────────╮
│ changes       to make an overview of all changed/added/deprecated items                                  │
│ coverage      to run coverage check of the documentation (if enabled)                                    │
│ devhelp       to make HTML files and a Devhelp project                                                   │
│ dirhtml       to make HTML files named index.html in directories                                         │
│ doctest       to run all doctests embedded in the documentation (if enabled)                             │
│ epub          to make an epub                                                                            │
│ gettext       to make PO message catalogs                                                                │
│ htmlhelp      to make HTML files and a HTML help project                                                 │
│ info          to make Texinfo files and run them through makeinfo                                        │
│ json          to make JSON files                                                                         │
│ latex         to make LaTeX files, you can set PAPER_SIZE=a4 or PAPER_SIZE=letter                        │
│ latexpdf      to make LaTeX files and run them through pdflatex                                          │
│ latexpdfja    to make LaTeX files and run them through platex/dvipdfmx                                   │
│ man           to make manual pages                                                                       │
│ pickle        to make pickle files                                                                       │
│ pseudoxml                                                                                                │
│ singlehtml    to make a single large HTML file                                                           │
│ texinfo       to make Texinfo files                                                                      │
│ text          to make text files                                                                         │
│ xml                                                                                                      │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Docs ───────────────────────────────────────────────────────────────────────────────────────────────────╮
│ clean         Delete built website files.                                                                │
│ html          to make standalone HTML files                                                              │
│ linkcheck     to check all external links for integrity                                                  │
│ serve         Build and serve standalone HTML files, with automatic rebuilds and live reload.            │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Code Quality ───────────────────────────────────────────────────────────────────────────────────────────╮
│ format        Format code and sort imports with ruff                                                     │
│ lint          Run tasks: ruff, mypy, and pyright (Run this before making a pull request!)                │
│ mypy          Typecheck using mypy                                                                       │
│ pyright       Typecheck using pyright                                                                    │
│ ruff-check    Run ruff check for code quality                                                            │
│ ruff-format   Format code using ruff                                                                     │
│ ruff-isort    Sort imports with ruff                                                                     │
│ test          Run unit tests (Run this before making a pull request!)                                    │
│ test-full     Run all tests                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Shell Completion ───────────────────────────────────────────────────────────────────────────────────────╮
│ whichshell    Find out which shell your system seems to be running                                       │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯

[pushfoo]

delete all or most "Docs Extra Formats" from make.py

Re-enabling these for epub and PDF is an eventual goal to my understanding. The rest can definitely be hidden or put on a subcommand.

[einarf]

Can we just quickly just expose only the options we use and get this out of the way?

I took 3 mins to do this quick edit: https://github.com/pythonarcade/arcade/pull/2629

 Usage: make.py [OPTIONS] COMMAND [ARGS]...                                                                                             

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --install-completion          Install completion for the current shell.                                                              │
│ --show-completion             Show completion for the current shell, to copy it or customize the installation.                       │
│ --help                        Show this message and exit.                                                                            │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Docs ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ clean         Delete built website files.                                                                                            │
│ html          to make standalone HTML files                                                                                          │
│ linkcheck     to check all external links for integrity                                                                              │
│ serve         Build and serve standalone HTML files, with automatic rebuilds and live reload.                                        │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Code Quality ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ format        Format code and sort imports with ruff                                                                                 │
│ lint          Run tasks: ruff, mypy, and pyright (Run this before making a pull request!)                                            │
│ mypy          Typecheck using mypy                                                                                                   │
│ pyright       Typecheck using pyright                                                                                                │
│ ruff-check    Run ruff check for code quality                                                                                        │
│ ruff-format   Format code using ruff                                                                                                 │
│ ruff-isort    Sort imports with ruff                                                                                                 │
│ test          Run unit tests (Run this before making a pull request!)                                                                │
│ test-full     Run all tests                                                                                                          │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

[eruvanos]

Looks good to me. Can we highlight the lint command somehow? for beginners it is the most important (and for me 😅 )

[einarf]

Change the grouping and descriptions a bit

Usage: make.py [OPTIONS] COMMAND [ARGS]...                                                                                             

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --install-completion          Install completion for the current shell.                                                              │
│ --show-completion             Show completion for the current shell, to copy it or customize the installation.                       │
│ --help                        Show this message and exit.                                                                            │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Docs ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ clean         Clean / Delete the documentation build directory                                                                       │
│ html          Build the documentation (HTML)                                                                                         │
│ linkcheck     Check for broken links in the documentation                                                                            │
│ serve         Build and serve the docs with automatic rebuilds and live reload.                                                      │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Code Quality ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ format        Format code (Run before making a pull request)                                                                         │
│ lint          Run tasks: ruff, mypy, and pyright (Run before making a pull request)                                                  │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Code Quality - Advanced ────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ mypy          Typecheck using mypy                                                                                                   │
│ pyright       Typecheck using pyright                                                                                                │
│ ruff-check    Run ruff check for code quality                                                                                        │
│ ruff-format   Format code using ruff                                                                                                 │
│ ruff-isort    Sort imports with ruff                                                                                                 │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Tests ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ test          Run unit tests                                                                                                         │
│ test-full     Run unit and integration tests                                                                                         │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

[einarf]

Merged. This is very easy to tweak later.