cf4cc29819
6 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
Antonio Ossa-Guerra
|
4da0851809
|
Add option to skip the first line of source code (#3299)
* Add option to skip the first line in source file This commit adds a CLi option to skip the first line in the source files, just like the Cpython command line allows [1]. By enabling the flag, using `-x` or `--skip-source-first-line`, the first line is removed temporarilly while the remaining contents are formatted. The first line is added back before returning the formatted output. [1]: https://docs.python.org/dev/using/cmdline.html#cmdoption-x Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl> * Add tests for `--skip-source-first-line` option When the flag is disabled (default), black formats the entire source file, as in every line. In the other hand, if the flag is enabled, by using `-x` or `--skip-source-first-line`, the first line is retained while the rest of the source is formatted and then is added back. These tests use an empty Python file that contains invalid syntax in its first line (`invalid_header.py`, at `miscellaneous/`). First, Black is invoked without enabling the flag which should result in an exit code different than 0. When the flag is enabled, Black is expected to return a successful exit code and the header is expected to be retained (even if its not valid Python syntax). Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl> * Support skip source first line option for blackd The recently added option can be added as an acceptable header for blackd. The arguments are passed in such a way that using the new header will activate the skip source first line behaviour as expected Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl> * Add skip source first line option to blackd docs The new option can be passed to blackd as a header. This commit updates the blackd docs to include the new header. Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl> * Update CHANGES.md Include the new Black option to skip the first line of source code in the configuration section Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl> * Update skip first line test including valid syntax Including valid Python syntax help us make sure that the file is still actually valid after skipping the first line of the source file (which contains invalid Python syntax) Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl> * Skip first source line at `format_file_in_place` Instead of skipping the first source line at `format_file_contents`, do it before. This allow us to find the correct newline and encoding on the actual source code (everything that's after the header). This change is also applied at Blackd: take the header before passing the source to `format_file_contents` and put the header back once we get the formatted result. Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl> * Test output newlines when skipping first line When skipping the first line of source code, the reference newline must be taken from the second line of the file instead of the first one, in case that the file mixes more than one kind of newline character Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl> * Test that Blackd also skips first line correctly Simliarly to the Black tests, we first compare that Blackd fails when the first line is invalid Python syntax and then check that the result is the expected when tha flag is activated Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl> * Use the content encoding to decode the header When decoding the header to put it back at the top of the contents of the file, use the same encoding used in the content. This should be a better "guess" that using the default value Signed-off-by: Antonio Ossa Guerra <aaossa@uc.cl> |
||
|
Alexandr Artemyev
|
07b68e2425
|
add preview option support for blackd (#3217)
Fixes #3195 Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com> |
||
|
Nimrod
|
8900e3ac8a
|
Add warning to not run blackd publicly in docs (#3167)
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com> |
||
|
Jelle Zijlstra
|
96bd428524
|
Quote black[jupyter] and black[d] in installation docs (#3006)
We just got someone on Discord who was confused because the command as written caused their shell to try to do command expansion. Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com> |
||
|
Richard Si
|
3d96b7f10a
|
Autogenerate black(d|-primer)? help in usage docs (#2212)
So these won't go out of date. This does mean the environment has be setup a bit more carefully so the right version of the tool is used, but thankfully the build environment is rebuilt on change on RTD anyway. Also since the HTML docs are known to build fine, let's provide downloadable HTMLzips of our docs. This change needs RTD and GH to install Black with the [d] extra so blackd's help can generated. While editing RTD's config file, let's migrate the file to a non-deprecated filename. Also I missed adding AUTHORS.md to the files key in the doc GHA config. |
||
|
Richard Si
|
62bfbd6a63
|
Reorganize docs v2 (GH-2174)
I know I know, this is the second reorganization of the docs. I'm not saying the first one was bad or anything... but.. actually wait nah, *it was bad*. Anyway, welcome to probably my biggest commit. The main thing with this reorganization was to introduce nesting to the documentation! Having all of the docs be part of the main TOC was becoming too much. There wasn't much room to expand either. Finally, the old setup required a documentation generation step which was just annoying. The goals of this reorganization was to: 1. Significantly restructure the docs to be discoverable and understandable 2. Add room for further docs (like guides or contributing docs) 3. Get rid of the doc generation step (it was slow and frustrating) 4. Unblock other improvements and also just make contributing to the docs easier Another important change with this is that we are no longer using GitHub as a documentation host. While GitHub does support Markdown based docs actually pretty well, the lack of any features outside of GitHub Flavoured Markdown is quite limiting. ReadTheDocs is just much better suited for documentation. You can use reST, MyST, CommonMark, and all of their great features like toctrees and admonitions. Related to this change, we're adopting MyST as our flavour of Markdown. MyST introduces neat syntax extensions to Markdown that pretty much gives us the best of both worlds. The ease of use and simplicity of MD and the flexibility and expressiveness of reST. Also recommonmark is deprecated now. This switch was possible now we don't use GH as a docs host. MyST docs have to be built to really be usable / pretty, so the MD docs are going to look pretty bad on GH, but that's fine now! Another thing that should be noted is that the README has been stripped of most content since it was confusing. Users would read the README and then think some feature or bug was fixed already and is available in a release when in reality, they weren't. They were reading effectively the latest docs without knowing. See also: https://github.com/psf/black/issues/1759 FYI: CommonMark is a rationalized version of Markdown syntax -- Commit history before merge: * Switch to MyST-Parser + doc config cleanup recommonmark is being deprecated in favour of MyST-Parser. This change is welcomed, especially since MyST-Parser has syntax extensions for the Commonmark standard. Effectively we get to use a language that's powerful and expressive like ReST, but get the simplicity of Markdown. The rest of this effort will be using some MyST features. This reorganization efforts aims to remove as much duplication as possible. The regeneration step once needed is gone, significantly simplifing our Sphinx documentation configuration. * Tell pipenv we replaced recommonmark for MyST-Parser Also update `docs/requirements.txt` * Delete all auto generated content * Switch prettier for mdformat (plus a few plugins) **FYI: THIS WAS EFFECTIVELY REVERTED, SEE THIRD TO LAST COMMIT** prettier doesn't support MyST's syntax extensions which are going to be used in this reorganization effort so we have to switch formatter. Unfortanately mdformat's style is different from prettier's so time to reformat the whole repo too. We're excluding .github/ISSUE_TEMPLATE because I have no idea whether its changes are safe, so let's play it safe. * Fix the heading levels in CHANGES.md + a link MyST-Parser / sphinx's linkcheck complains otherwise. * Move reference docs into a docs/contributing dir They're for contributors of Black anyway. Also added a note in the summary document warning about the lack of attention the reference has been dealing with. * Rewrite and setup the new landing page + main TOC - add some more detail about Black's beta status - add licensing info - add external links in the main TOC for GitHub, PyPI, and IRC - prepare main TOC for new structure * Break out AUTHORS into its own file Not only was the AUTHORS list quite long, this makes it easy to include it in the Sphinx docs with just a simple symlink. * Add license to docs via a simple include Yes the document is orphaned but it is linked to in the landing page (docs/index.rst). * Add "The Black Code Style" section This mostly was a restructuring commit, there has been a few updates but not many. The main goal was to split "current style" and "planned changes to the style that haven't happened yet" to avoid confusion. * Add "Getting Started" page This is basically a quick start + even more. This commit is certainly one of most creatively involved in this effort. * Add "Usage and Configuration" section This commit was as much restructuring as new content. Instead of being in one giant file, usage and configuration documentation can expand without bloating a single file. * Add "Integrations" section Just a restructuring commit ... * Add "Guides" section This is a promising area of documentation that could easily grow in the future, let's prepare for that! * Add "Contributing" section This is also another area that I expect to see significant growth in. Contributors to Black could definitely do with some more specific docs that clears up certain parts of our slightly confusing project (it's only confusing because we're getting big and old!). * Rewrite CONTRIBUTING.md to just point to RTD * Rewrite README.md to delegate most info to RTD * Address feedback + a lot of corrections and edits I know I said I wanted to do these after landing this but given there's going to be no time between this being merged and a release getting pushed, I want these changes to make it in. - drop the number flag for mdformat - to reduce diffs, see also: https://mdformat.readthedocs.io/en/stable/users/style.html#ordered-lists - the GH issue templates should be safe by mdformat, so get rid of the exclude - clarify our configuration position - i.e. stop claiming we don't have many options, instead say we want as little formatting knobs as possible - lots and lots of punctuation, spelling, and grammar corrections (thanks Jelle!) - use RTD as the source for the CHANGELOG too - visual style cleanups - add docs about our .gitignore behaviour - expand GHA Action docs - clarify we want the PR number in the CHANGELOG entry - claify Black's behaviour for with statements post Python 3.9 - italicize a bunch of "Black"s Thank you goes to Jelle, Taneli (hukkinj1 on GH), Felix (felix-hilden on GH), and Wouter (wbolster on GH) for the feedback! * Merge remote-tracking branch 'upstream/master' into reorganize-docs-v2 merge conflicts suck, although these ones weren't too bad. * Add changelog entry + fix merge conflict resolution error I consider this important enough to be worthy of a changelog entry :) * Merge branch 'master' into reorganize-docs-v2 Co-authored-by: Łukasz Langa <lukasz@langa.pl> * Actually let's continue using prettier Prettier works fine for all of the default MyST syntax so let's not rock the boat as much. Dropping the mdformat commit was merge-conflict filled so here's additional commit instead. * Address Cooper's, Taneli's, and Jelle's feedback Lots of wording improvements by Cooper. Taneli suggested to disable the enabled by default MyST syntax not supported by Prettier and I agreed. And Jelle found one more spelling error! * More minor fixes |