Commit history before merge:
* Replace references to master branch
* Update .flake8 to reference docs on RTD
We're moving away from GitHub as a documentation host to only RTD because
it's makes our lives easier creating good docs. I know this link is dead right now,
but it won't be once we release a new version with the documentation reorganization
changes (which should be soon!).
Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
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
This commit simplifies entrypoint.sh for GitHub Actions by removing
duplication of args and black_args (cf. #1909).
The reason why #1909 uses the input id black_args is to avoid an overlap
with args, but this naming seems redundant. So let me suggest option
and src, which are consistent with CLI. Backward compatibility is
guaranteed; Users can still use black_args as well.
Commit history pre-merge:
* Simplify GitHub Action entrypoint (#1909)
* Fix prettier
* Emit a warning message when `black_args` is used
This deprecation should be visible in GitHub Action's UI now.
Co-authored-by: Shota Ray Imaki <shota.imaki.0801@gmail.com>
Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
Travis CI for Open Source is shutting down in a few weeks so the queue
for jobs is insane due to lower resources. I'm 99.99% sure we don't need
it as our Test, Lint, Docs, Upload / Package, Primer, and Fuzz workflows
are all on GitHub Actions. So even though we *can* migrate to the .com
version with its 1000 free Linux minutes(?), I don't think we need to.
more information here:
- https://blog.travis-ci.com/oss-announcement
- https://blog.travis-ci.com/2020-11-02-travis-ci-new-billing
- https://docs.travis-ci.com/user/migrate/open-source-repository-migration
This commit does the following:
- delete the Travis CI configuration
- add to the GHA test workflows so coverage continues to be recorded
- tweaked coverage configuration so this wouldn't break
- remove any references to Travis CI in the docs (i.e. readme + sphinx
docs)
Regarding the Travis CI to GitHub Actions Coveralls transition, the
official action doesn't support the coverage files produced by coverage.py
unfornately. Also no, I don't really know what I am doing so don't @ me
if this breaks :p (well you can, but don't expect me to be THAT useful).
The Coveralls setup has two downfalls AFAIK:
- Only Linux runs are used because AndreMiras/coveralls-python-action
only supports Linux. Although this isn't a big issue since the Travis
Coveralls configuration only used Linux data too.
- Pull requests from an internal branch (i.e. one on psf/black) will be
marked as a push coverage build by Coveralls since our anti-duplicate-
workflows system runs under the push even for such cases.
* Added support for top-level user configuration
At the user level, a TOML config can be specified in the following locations:
* Windows: ~\.black
* Unix-like: $XDG_CONFIG_HOME/black (~/.config/black fallback)
Instead of changing env vars for the entire black-primer process, they
are now changed only for the black subprocess, using a tmpdir.
* Update example exclude to match only files in root
The `exclude` section of the example `pyproject.toml` file didn't work
as expected. It claimed to exclude matched files only in the project
root, but it actually excluded matched files at any directory level
within the project. We can address this by prepending `^/` to the regex
to ensure that it only matches files in the project root.
See https://github.com/psf/black/issues/1473#issuecomment-740008873 for
explanation.
* Mention excluding directories as well
* Gets gh-action ready for marketplace release
* Updates documentation and removes redundant gh-action input argument
* Fixes gh-action bug
This commit fixes a bug which caused not all input arguments were forwarder to the black formatter.
* Update README.md
Co-authored-by: Cooper Lees <me@cooperlees.com>
Co-authored-by: Cooper Lees <me@cooperlees.com>
* Provide a stdin-filename to allow stdin to respect exclude/force-exclude rules
This will allow automatic tools to enforce the project's
exclude/force-exclude rules even if they pass the file through stdin to
update its buffer.
This is a similar solution to --stdin-display-name in flake8.
* Update src/black/__init__.py
Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
* --stdin-filename should only respect --exclude-filename
* Update README with the new --stdin-filename option
* Write some tests for the new stdin-filename functionality
* Apply suggestions from code review
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
* Force stdin output when we asked for stdin even if the file exists
* Add an entry in the changelog regarding --stdin-filename
* Reduce disk reads if possible
Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
* Check for is_stdin and p.is_file before checking for p.is_dir()
Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com>
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
* Allow default params overriding.
* Update: docs and action.yaml.
* The second contirbution, add my name to authors.md
* Correct docs `with.args` example.
* Just to rerun the Travis jobs.
* chmod 755
* Repair colorama wrapping on non-Windows platforms
The wrap_stream_for_windows() function calls
colorama.initialise.wrap_stream() function to apply colorama's magic to
wrapper to the output stream. Except this wrapper is only applied on
Windows platforms that need it, otherwise the original stream is
returned as-is.
The colorama wrapped stream lacks a detach() method, so a no-op lambda
was being assigned to the wrapped stream.
The problem is that the no-op lambda was being assigned unconditionally
whether or not colorama actually returns a wrapped stream, thus
replacing the original TextIOWrapper's detach() method. Replacing the
detach() method with a no-op lambda is the root cause of the problem
observed in #1664.
The solution is to only assign the no-op detach() method if the stream
lacks its own detach() method.
Repairs #1664
* Add link to conda-forge integration
resolves#1686
* README: keep PyPI tags together
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
* 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
Stable tag wasn't available and crashed when attempting to set initial
pre-commit. Also the python version needs to be installed so it would
be better to use the generic "python3" command.
Black wouldn't be where it is without the countless outside contributions.
So thank you y'all and we will share our appreciation by listing your names
(and emails) in the README.md :D
* Implement a re-usable GitHub Action
Implement a GitHub action that can be reused across projects that want
to run black as part of their CI workflows.
* Fix typo in README.md
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
* Use latest Python 3
Co-authored-by: Hugo van Kemenade <hugovk@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.
* Update docs about stable tag now being a branch
Issue #760 had the `stable` tag changed to a branch since it was causing a few issues. This updates the docs to reflect that change.
* Make the prettier hook pass
* Improve wording
