7403d95862
* Split code style and components documentation Splits 'the_black_code_style', 'pragmatism', 'blackd',and 'black_primer' into their own files. The exception being 'the_black_code_style' and 'pragmatism'. They have been merged into one 'the_black_code_style_and_pragmatism' file. These changes are being made because the README is becoming very long. And a README isn't great if it dissuades its reader because of its length. * Update the doc generation logic and configuration With the moving of several sections in the README and the renaming of a few files, 'conf.py' needs to be able to support custom sections. This commit introduces DocSection which can be used to specify custom sections of documentation. The information stored in DocSection will be used by the process_sections function to read, process, and write the section to CURRENT_DIR. A large change has been made to the how the docs are prepared to be built. Instead of just generating the files needed by reading the README, this has a full chain of operations so custom sections are supported. First, it reads the README and spits out a list of DocSection objects representing the sections to be generated by process_sections. This is done since most of the docs still live in README. Then along with the defined custom_sections , the process_sections will be begin to process the DocSection objects. It reads the information it needs to generate the section. Then fetches the section's contents, calls processors required by the section to process the section's contents, and finally writes the section to CURRENT_DIR. This large change is so processing of the documentation can be done just for the versions hosted on ReadTheDocs.org. An example processor using this feature is a 'replace_links' processor. It will replace documentation links that point to the docs hosted on GitHub with links that point to the version hosted on ReadTheDocs.org. (I won't be coding that ATM) This also means that files will be overwritten or created once the docs have been built. It is annoying, since you have to 'git reset --hard' and 'git clean -f -d' after each build, but there's nothing better. The old system had the same side effects, so yeah :( * Update filenames and delete unnecessary files Update the filenames since 'the_black_code_style' and 'pragmatism' were merged and 'contributing' was deleted in favor of 'contributing_to_black'. All symlinks were deleted since their home (_build/generated) is no longer used. * Fix broken links and a few redirections * Merge master into refactor_docs (manually done) * Add my and most of @hugovk suggestions Co-Authored-By: Hugo van Kemenade <hugovk@users.noreply.github.com> * Add logging and improve configurability Just some cleaning up up of the DocSection dataclass and added logging support so you know what's going on. * Rename a section and please the grammar gods of Black Thanks @hugovk for the suggestion! * Fix Markdown comments * Add myself as an author :P Seems like the right time. Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
3.8 KiB
3.8 KiB
black-primer
black-primer is a tool built for CI (and humans) to have Black --check a number of
(configured in primer.json) Git accessible projects in parallel. (A PR will be
accepted to add Mercurial support.)
Run flow
- Ensure we have a
black+gitin PATH - Load projects from
primer.json - Run projects in parallel with
--workerworkers (defaults to CPU count / 2)- Checkout projects
- Run black and record result
- Clean up repository checkout (can optionally be disabled via
--keep)
- Display results summary to screen
- Default to cleaning up
--work-dir(which defaults to tempfile schemantics) - Return
- 0 for successful run
- < 0 for environment / internal error
- > 0 for each project with an error
Speed up runs 🏎
If you're running locally yourself to test black on lots of code try:
- Using
-k/--keep+-w/--work-dirso you don't have to re-checkout the repo each run
CLI arguments
Usage: black-primer [OPTIONS]
primer - prime projects for blackening... 🏴
Options:
-c, --config PATH JSON config file path [default: /Users/cooper/repos/
black/src/black_primer/primer.json]
--debug Turn on debug logging [default: False]
-k, --keep Keep workdir + repos post run [default: False]
-L, --long-checkouts Pull big projects to test [default: False]
-R, --rebase Rebase project if already checked out [default:
False]
-w, --workdir PATH Directory path for repo checkouts [default: /var/fol
ders/tc/hbwxh76j1hn6gqjd2n2sjn4j9k1glp/T/primer.20200
517125229]
-W, --workers INTEGER Number of parallel worker coroutines [default: 2]
-h, --help Show this message and exit.
primer config file
The config is JSON format. Its main element is the "projects" dictionary. Below
explains each parameter:
{
"projects": {
"00_Example": {
"cli_arguments": "List of extra CLI arguments to pass Black for this project",
"expect_formatting_changes": "Boolean to indicate that the version of Black is expected to cause changes",
"git_clone_url": "URL you would pass `git clone` to check out this repo",
"long_checkout": "Boolean to have repo skipped by default unless `--long-checkouts` is specified",
"py_versions": "List of major Python versions to run this project with - all will do as you'd expect - run on ALL versions"
},
"aioexabgp": {
"cli_arguments": [],
"expect_formatting_changes": true,
"git_clone_url": "https://github.com/cooperlees/aioexabgp.git",
"long_checkout": false,
"py_versions": ["all", "3.8"] // "all" ignores all other versions
}
}
}
Example run
cooper-mbp:black cooper$ ~/venvs/b/bin/black-primer
[2020-05-17 13:06:40,830] INFO: 4 projects to run Black over (lib.py:270)
[2020-05-17 13:06:44,215] INFO: Analyzing results (lib.py:285)
-- primer results 📊 --
3 / 4 succeeded (75.0%) ✅
1 / 4 FAILED (25.0%) 💩
- 0 projects disabled by config
- 0 projects skipped due to Python version
- 0 skipped due to long checkout
Failed projects:
## flake8-bugbear:
- Returned 1
- stdout:
--- tests/b303_b304.py 2020-05-17 20:04:09.991227 +0000
+++ tests/b303_b304.py 2020-05-17 20:06:42.753851 +0000
@@ -26,11 +26,11 @@
maxint = 5 # this is okay
# the following shouldn't crash
(a, b, c) = list(range(3))
# it's different than this
a, b, c = list(range(3))
- a, b, c, = list(range(3))
+ a, b, c = list(range(3))
# and different than this
(a, b), c = list(range(3))
a, *b, c = [1, 2, 3, 4, 5]
b[1:3] = [0, 0]
would reformat tests/b303_b304.py
Oh no! 💥 💔 💥
1 file would be reformatted, 22 files would be left unchanged.