Black used to erroneously remove all empty lines between non-function
code and decorators when formatting typing stubs. Now a single empty
line is enforced.
I chose for putting empty lines around decorated classes that have empty
bodies since removing empty lines around such classes would cause a
formatting issue that seems to be impossible to fix.
For example:
```
class A: ...
@some_decorator
class B: ...
class C: ...
class D: ...
@some_other_decorator
def foo(): -> None: ...
```
It is easy to enforce no empty lines between class A, B, and C.
Just return 0, 0 for a line that is a decorator and precedes an stub
class. Fortunately before this commit, empty lines after that class
would be removed already.
Now let's look at the empty line between class D and function foo. In
this case, there should be an empty line there since it's class code next
to function code. The problem is that when deciding to add X empty lines
before a decorator, you can't tell whether it's before a class or a
function. If the decorator is before a function, then an empty line
is needed, while no empty lines are needed when the decorator is
before a class.
So even though I personally prefer no empty lines around decorated
classes, I had to go the other way surrounding decorated classes with
empty lines.
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
* Fix incorrect space before colon in if/while stmts
Previously Black would format this code
```
if (foo := True):
print(foo)
```
as
```
if (foo := True) :
print(foo)
```
adding an incorrect space after the RPAR. Buggy code in the
normalize_invisible_parens function caused the colon to be wrapped in
invisible parentheses. The LPAR of that pair was then prefixed with a
single space at the request of the whitespace function.
This commit fixes the accidental skipping of a pre-condition check
which must return True before parenthesis normalization of a specific
child Leaf or Node can happen. The pre-condition check being skipped
was why the colon was wrapped in invisible parentheses.
* Add an entry in CHANGES.md
The quotes of multiline docstrings are now only normalized when string
normalization is off, instead of the string normalization setting being
ignored and the quotes being *always* normalized.
I had to make a new test case and data file since the current pair for
docstrings only worked when there is no formatting difference between the
formatting results with string normalization on and off. I needed to add
tests for when there *are* differences between the two. So I split
test_docstring's test code when string normalization is disabled into a
new test case along with a new data file.
* Upgrade docs to Sphinx 3+
* Fix all the warnings...
- Fixed bad docstrings
- Fixed bad fenced code blocks in documentation
- Blocklisted some sections from being generated from the README
- Added missing documentation to index.rst
- Fixed an invalid autofunction directive in reference/reference_functions.rst
- Pin another documentation dependency
* Add documentation build test
Isort 5 introduced profiles and ensure_newline_before_comments options. Either needs to be added to work correctly with black.
Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
* 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>
* Make the sidebar navigation scrollable
This is necessary since we have so many documentation sections that even
on a desktop screen, the navigation can sometimes be clipped. The only
annoyance is that on Firefox, the scrollbar can't be hidden :(
* allow the docs to build
* Add `black-primer` docs
- Document the idea, CLI args, config and a example run for `black-primer` in README.md
- Add to docs/index.rst
* Add @hugovk suggestions - Thanks.
* Add Black compatible configs in docs ( #1366 & #1205)
When users of Black are starting a new project or are adding Black to their
existing projects, they will usually have to config their existing tools like
flake8 to be compatible with Black. Usually, these configs are the same across
different projects. Yet, there isn't any consolidated infomation on what configs
are compatible. Leaving users of Black to dig out any infomation they can find
in README.md.
* Fix a bad max-line-length value
* Clean up pylint's configs
* Add explanations for each configurations
Copying and pasting code without understanding it is a bad idea. This goes the same
for users copying and pasting configurations.
* Capitalize Pylint
* Link from the README
* Fix the isort configuration
I referenced the wrong source. I used a pesonal configuration, not a pure Black-
compatible configuration.
* Improve the config explanations
The explanation for the isort configuration was pretty bad. After having fixed the
configuration (see commit 01c55d1), improving the its explanation was necessary to
make it more user-friendly and understandable. Also added fenced code blocks of the
raw configuration options so the explanations make sense.
* Improve README wording slightly
* Add @hugovk, @JelleZijlstra + my suggestions
Co-authored-by: Cooper Lees <cooper@fb.com>
* Remove reference to format_int_string in docs
The function got dropped in 250ba7f04b.
* Remove reference to is_python36 in docs
The function got removed in 36d3c516d3.
* add test for special unicode symbol which usual re can not process correctly
add regex lib which supports unicode 12.1.0 standard
replace re usage in project in favor to regex
* #455 fix dependency
The default behaviour is that now all lines break *before* delimiters,
instead of afterwards. The special cases for this are commas and
behaviour around args.
Resolves#73
Most is not generated from README.md so we no longer have to remember to update
two Change Logs, and so on!
If we decide to diverge from the README in Sphinx, that's fine, too. We will
just create dedicated documents.
