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>
71 lines
1.9 KiB
ReStructuredText
71 lines
1.9 KiB
ReStructuredText
.. black documentation master file, created by
|
|
sphinx-quickstart on Fri Mar 23 10:53:30 2018.
|
|
|
|
The uncompromising code formatter
|
|
=================================
|
|
|
|
By using *Black*, you agree to cede control over minutiae of
|
|
hand-formatting. In return, *Black* gives you speed, determinism, and
|
|
freedom from `pycodestyle` nagging about formatting. You will save time
|
|
and mental energy for more important matters.
|
|
|
|
*Black* makes code review faster by producing the smallest diffs
|
|
possible. Blackened code looks the same regardless of the project
|
|
you're reading. Formatting becomes transparent after a while and you
|
|
can focus on the content instead.
|
|
|
|
Try it out now using the `Black Playground <https://black.now.sh>`_.
|
|
|
|
.. note::
|
|
|
|
`Black is beta <installation_and_usage.html#note-this-is-a-beta-product>`_.
|
|
|
|
|
|
Testimonials
|
|
------------
|
|
|
|
**Dusty Phillips**, `writer <https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips>`_:
|
|
|
|
*Black is opinionated so you don't have to be.*
|
|
|
|
**Hynek Schlawack**, creator of `attrs <https://www.attrs.org/>`_, core
|
|
developer of Twisted and CPython:
|
|
|
|
*An auto-formatter that doesn't suck is all I want for Xmas!*
|
|
|
|
**Carl Meyer**, `Django <https://www.djangoproject.com/>`_ core developer:
|
|
|
|
*At least the name is good.*
|
|
|
|
**Kenneth Reitz**, creator of `requests <http://python-requests.org/>`_
|
|
and `pipenv <https://docs.pipenv.org/>`_:
|
|
|
|
*This vastly improves the formatting of our code. Thanks a ton!*
|
|
|
|
Contents
|
|
--------
|
|
|
|
.. toctree::
|
|
:maxdepth: 2
|
|
|
|
installation_and_usage
|
|
the_black_code_style
|
|
pyproject_toml
|
|
editor_integration
|
|
blackd
|
|
black_primer
|
|
version_control_integration
|
|
ignoring_unmodified_files
|
|
contributing_to_black
|
|
show_your_style
|
|
change_log
|
|
reference/reference_summary
|
|
authors
|
|
|
|
Indices and tables
|
|
==================
|
|
|
|
* :ref:`genindex`
|
|
* :ref:`modindex`
|
|
* :ref:`search`
|