From: Gunung P. Wibisono <55311527+gunungpw@users.noreply.github.com> Date: Wed, 30 Mar 2022 20:43:46 +0000 (+0700) Subject: Convert `index.rst` and `license.rst` to markdown (#2852) X-Git-Url: https://git.madduck.net/etc/vim.git/commitdiff_plain/3dea6e363562050ae032c80a648bd88fc49381bc Convert `index.rst` and `license.rst` to markdown (#2852) Co-authored-by: Richard Si <63936253+ichard26@users.noreply.github.com> --- diff --git a/docs/conf.py b/docs/conf.py index 2801e0e..e9fdebb 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -105,11 +105,15 @@ myst_heading_anchors = 3 # Prettier support formatting some MyST syntax but not all, so let's disable the # unsupported yet still enabled by default ones. myst_disable_syntax = [ + "colon_fence", "myst_block_break", "myst_line_comment", "math_block", ] +# Optional MyST Syntaxes +myst_enable_extensions = [] + # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for diff --git a/docs/contributing/index.md b/docs/contributing/index.md new file mode 100644 index 0000000..f56e57c --- /dev/null +++ b/docs/contributing/index.md @@ -0,0 +1,49 @@ +# Contributing + +```{toctree} +--- +hidden: +--- + +the_basics +gauging_changes +issue_triage +release_process +reference/reference_summary +``` + +Welcome! Happy to see you willing to make the project better. Have you read the entire +[user documentation](https://black.readthedocs.io/en/latest/) yet? + +```{rubric} Bird's eye view + +``` + +In terms of inspiration, _Black_ is about as configurable as _gofmt_ (which is to say, +not very). This is deliberate. _Black_ aims to provide a consistent style and take away +opportunities for arguing about style. + +Bug reports and fixes are always welcome! Please follow the +[issue template on GitHub](https://github.com/psf/black/issues/new) for best results. + +Before you suggest a new feature or configuration knob, ask yourself why you want it. If +it enables better integration with some workflow, fixes an inconsistency, speeds things +up, and so on - go for it! On the other hand, if your answer is "because I don't like a +particular formatting" then you're not ready to embrace _Black_ yet. Such changes are +unlikely to get accepted. You can still try but prepare to be disappointed. + +```{rubric} Contents + +``` + +This section covers the following topics: + +- {doc}`the_basics` +- {doc}`gauging_changes` +- {doc}`release_process` +- {doc}`reference/reference_summary` + +For an overview on contributing to the _Black_, please checkout {doc}`the_basics`. + +If you need a reference of the functions, classes, etc. available to you while +developing _Black_, there's the {doc}`reference/reference_summary` docs. diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst deleted file mode 100644 index 480dbd6..0000000 --- a/docs/contributing/index.rst +++ /dev/null @@ -1,43 +0,0 @@ -Contributing -============ - -.. toctree:: - :hidden: - - the_basics - gauging_changes - issue_triage - release_process - reference/reference_summary - -Welcome! Happy to see you willing to make the project better. Have you read the entire -`user documentation `_ yet? - -.. rubric:: Bird's eye view - -In terms of inspiration, *Black* is about as configurable as *gofmt* (which is to say, -not very). This is deliberate. *Black* aims to provide a consistent style and take away -opportunities for arguing about style. - -Bug reports and fixes are always welcome! Please follow the -`issue template on GitHub `_ for best results. - -Before you suggest a new feature or configuration knob, ask yourself why you want it. If -it enables better integration with some workflow, fixes an inconsistency, speeds things -up, and so on - go for it! On the other hand, if your answer is "because I don't like a -particular formatting" then you're not ready to embrace *Black* yet. Such changes are -unlikely to get accepted. You can still try but prepare to be disappointed. - -.. rubric:: Contents - -This section covers the following topics: - -- :doc:`the_basics` -- :doc:`gauging_changes` -- :doc:`release_process` -- :doc:`reference/reference_summary` - -For an overview on contributing to the *Black*, please checkout :doc:`the_basics`. - -If you need a reference of the functions, classes, etc. available to you while -developing *Black*, there's the :doc:`reference/reference_summary` docs. diff --git a/docs/guides/index.md b/docs/guides/index.md new file mode 100644 index 0000000..127279b --- /dev/null +++ b/docs/guides/index.md @@ -0,0 +1,16 @@ +# Guides + +```{toctree} +--- +hidden: +--- + +introducing_black_to_your_project +using_black_with_other_tools +``` + +Wondering how to do something specific? You've found the right place! Listed below are +topic specific guides available: + +- {doc}`introducing_black_to_your_project` +- {doc}`using_black_with_other_tools` diff --git a/docs/guides/index.rst b/docs/guides/index.rst deleted file mode 100644 index 717c5c4..0000000 --- a/docs/guides/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -Guides -====== - -.. toctree:: - :hidden: - - introducing_black_to_your_project - using_black_with_other_tools - -Wondering how to do something specific? You've found the right place! Listed below -are topic specific guides available: - -- :doc:`introducing_black_to_your_project` -- :doc:`using_black_with_other_tools` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..9d0db46 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,139 @@ + + +# The uncompromising code formatter + +> “Any color you like.” + +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.vercel.app). + +```{admonition} Note - Black is now stable! +*Black* is [successfully used](https://github.com/psf/black#used-by) by +many projects, small and big. *Black* has a comprehensive test suite, with efficient +parallel tests, our own auto formatting and parallel Continuous Integration runner. +Now that we have become stable, you should not expect large formatting to changes in +the future. Stylistic changes will mostly be responses to bug reports and support for new Python +syntax. + +Also, as a safety measure which slows down processing, *Black* will check that the +reformatted code still produces a valid AST that is effectively equivalent to the +original (see the +[Pragmatism](./the_black_code_style/current_style.md#pragmatism) +section for details). If you're feeling confident, use `--fast`. +``` + +```{note} +{doc}`Black is licensed under the MIT license `. +``` + +## Testimonials + +**Mike Bayer**, author of [SQLAlchemy](https://www.sqlalchemy.org/): + +> _I can't think of any single tool in my entire programming career that has given me a +> bigger productivity increase by its introduction. I can now do refactorings in about +> 1% of the keystrokes that it would have taken me previously when we had no way for +> code to format itself._ + +**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!_ + +## Show your style + +Use the badge in your project's README.md: + +```md +[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) +``` + +Using the badge in README.rst: + +```rst +.. image:: https://img.shields.io/badge/code%20style-black-000000.svg + :target: https://github.com/psf/black +``` + +Looks like this: + +```{image} https://img.shields.io/badge/code%20style-black-000000.svg +:target: https://github.com/psf/black +``` + +## Contents + +```{toctree} +--- +maxdepth: 3 +includehidden: +--- + +the_black_code_style/index +``` + +```{toctree} +--- +maxdepth: 3 +includehidden: +caption: User Guide +--- + +getting_started +usage_and_configuration/index +integrations/index +guides/index +faq +``` + +```{toctree} +--- +maxdepth: 2 +includehidden: +caption: Development +--- + +contributing/index +change_log +authors +``` + +```{toctree} +--- +hidden: +caption: Project Links +--- + +GitHub +PyPI +Chat +``` + +# Indices and tables + +- {ref}`genindex` +- {ref}`search` diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 8a8da0d..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,131 +0,0 @@ -.. black documentation master file, created by - sphinx-quickstart on Fri Mar 23 10:53:30 2018. - -The uncompromising code formatter -================================= - - “Any color you like.” - -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 `_. - -.. admonition:: Note - Black is now stable! - - *Black* is `successfully used `_ by - many projects, small and big. *Black* has a comprehensive test suite, with efficient - parallel tests, our own auto formatting and parallel Continuous Integration runner. - Now that we have become stable, you should not expect large formatting to changes in - the future. Stylistic changes will mostly be responses to bug reports and support for new Python - syntax. - - Also, as a safety measure which slows down processing, *Black* will check that the - reformatted code still produces a valid AST that is effectively equivalent to the - original (see the - `Pragmatism <./the_black_code_style/current_style.html#pragmatism>`_ - section for details). If you're feeling confident, use ``--fast``. - -.. note:: - :doc:`Black is licensed under the MIT license `. - -Testimonials ------------- - -**Mike Bayer**, author of `SQLAlchemy `_: - - *I can't think of any single tool in my entire programming career that has given me a - bigger productivity increase by its introduction. I can now do refactorings in about - 1% of the keystrokes that it would have taken me previously when we had no way for - code to format itself.* - -**Dusty Phillips**, `writer `_: - - *Black is opinionated so you don't have to be.* - -**Hynek Schlawack**, creator of `attrs `_, core -developer of Twisted and CPython: - - *An auto-formatter that doesn't suck is all I want for Xmas!* - -**Carl Meyer**, `Django `_ core developer: - - *At least the name is good.* - -**Kenneth Reitz**, creator of `requests `_ -and `pipenv `_: - - *This vastly improves the formatting of our code. Thanks a ton!* - - -Show your style ---------------- - -Use the badge in your project's README.md: - -.. code-block:: md - - [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) - - -Using the badge in README.rst: - -.. code-block:: rst - - .. image:: https://img.shields.io/badge/code%20style-black-000000.svg - :target: https://github.com/psf/black - -Looks like this: - -.. image:: https://img.shields.io/badge/code%20style-black-000000.svg - :target: https://github.com/psf/black - -Contents --------- - -.. toctree:: - :maxdepth: 3 - :includehidden: - - the_black_code_style/index - -.. toctree:: - :maxdepth: 3 - :includehidden: - :caption: User Guide - - getting_started - usage_and_configuration/index - integrations/index - guides/index - faq - -.. toctree:: - :maxdepth: 2 - :includehidden: - :caption: Development - - contributing/index - change_log - authors - -.. toctree:: - :hidden: - :caption: Project Links - - GitHub - PyPI - Chat - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`search` diff --git a/docs/integrations/index.md b/docs/integrations/index.md new file mode 100644 index 0000000..33135d0 --- /dev/null +++ b/docs/integrations/index.md @@ -0,0 +1,31 @@ +# Integrations + +```{toctree} +--- +hidden: +--- + +editors +github_actions +source_version_control +``` + +_Black_ can be integrated into many environments, providing a better and smoother +experience. Documentation for integrating _Black_ with a tool can be found for the +following areas: + +- {doc}`Editor / IDE <./editors>` +- {doc}`GitHub Actions <./github_actions>` +- {doc}`Source version control <./source_version_control>` + +Editors and tools not listed will require external contributions. + +Patches welcome! ✨ 🍰 ✨ + +Any tool can pipe code through _Black_ using its stdio mode (just +[use `-` as the file name](https://www.tldp.org/LDP/abs/html/special-chars.html#DASHREF2)). +The formatted code will be returned on stdout (unless `--check` was passed). _Black_ +will still emit messages on stderr but that shouldn't affect your use case. + +This can be used for example with PyCharm's or IntelliJ's +[File Watchers](https://www.jetbrains.com/help/pycharm/file-watchers.html). diff --git a/docs/integrations/index.rst b/docs/integrations/index.rst deleted file mode 100644 index ed62ebc..0000000 --- a/docs/integrations/index.rst +++ /dev/null @@ -1,28 +0,0 @@ -Integrations -============ - -.. toctree:: - :hidden: - - editors - github_actions - source_version_control - -*Black* can be integrated into many environments, providing a better and smoother experience. Documentation for integrating *Black* with a tool can be found for the -following areas: - -- :doc:`Editor / IDE <./editors>` -- :doc:`GitHub Actions <./github_actions>` -- :doc:`Source version control <./source_version_control>` - -Editors and tools not listed will require external contributions. - -Patches welcome! ✨ 🍰 ✨ - -Any tool can pipe code through *Black* using its stdio mode (just -`use \`-\` as the file name `_). -The formatted code will be returned on stdout (unless ``--check`` was passed). *Black* -will still emit messages on stderr but that shouldn't affect your use case. - -This can be used for example with PyCharm's or IntelliJ's -`File Watchers `_. diff --git a/docs/license.md b/docs/license.md new file mode 100644 index 0000000..132c95b --- /dev/null +++ b/docs/license.md @@ -0,0 +1,9 @@ +--- +orphan: true +--- + +# License + +```{include} ../LICENSE + +``` diff --git a/docs/license.rst b/docs/license.rst deleted file mode 100644 index 2dc20a2..0000000 --- a/docs/license.rst +++ /dev/null @@ -1,6 +0,0 @@ -:orphan: - -License -======= - -.. include:: ../LICENSE diff --git a/docs/the_black_code_style/index.md b/docs/the_black_code_style/index.md new file mode 100644 index 0000000..d150855 --- /dev/null +++ b/docs/the_black_code_style/index.md @@ -0,0 +1,47 @@ +# The Black Code Style + +```{toctree} +--- +hidden: +--- + +Current style +Future style +``` + +_Black_ is a PEP 8 compliant opinionated formatter with its own style. + +While keeping the style unchanged throughout releases has always been a goal, the +_Black_ code style isn't set in stone. It evolves to accommodate for new features in the +Python language and, occasionally, in response to user feedback. Large-scale style +preferences presented in {doc}`current_style` are very unlikely to change, but minor +style aspects and details might change according to the stability policy presented +below. Ongoing style considerations are tracked on GitHub with the +[design](https://github.com/psf/black/labels/T%3A%20design) issue label. + +## Stability Policy + +The following policy applies for the _Black_ code style, in non pre-release versions of +_Black_: + +- The same code, formatted with the same options, will produce the same output for all + releases in a given calendar year. + + This means projects can safely use `black ~= 22.0` without worrying about major + formatting changes disrupting their project in 2022. We may still fix bugs where + _Black_ crashes on some code, and make other improvements that do not affect + formatting. + +- The first release in a new calendar year _may_ contain formatting changes, although + these will be minimised as much as possible. This is to allow for improved formatting + enabled by newer Python language syntax as well as due to improvements in the + formatting logic. + +- The `--preview` flag is exempt from this policy. There are no guarantees around the + stability of the output with that flag passed into _Black_. This flag is intended for + allowing experimentation with the proposed changes to the _Black_ code style. + +Documentation for both the current and future styles can be found: + +- {doc}`current_style` +- {doc}`future_style` diff --git a/docs/the_black_code_style/index.rst b/docs/the_black_code_style/index.rst deleted file mode 100644 index 511a6ec..0000000 --- a/docs/the_black_code_style/index.rst +++ /dev/null @@ -1,47 +0,0 @@ -The Black Code Style -==================== - -.. toctree:: - :hidden: - - Current style - Future style - -*Black* is a PEP 8 compliant opinionated formatter with its own style. - -While keeping the style unchanged throughout releases has always been a goal, -the *Black* code style isn't set in stone. It evolves to accommodate for new features -in the Python language and, occasionally, in response to user feedback. -Large-scale style preferences presented in :doc:`current_style` are very unlikely to -change, but minor style aspects and details might change according to the stability -policy presented below. Ongoing style considerations are tracked on GitHub with the -`design `_ issue label. - -Stability Policy ----------------- - -The following policy applies for the *Black* code style, in non pre-release -versions of *Black*: - -- The same code, formatted with the same options, will produce the same - output for all releases in a given calendar year. - - This means projects can safely use `black ~= 22.0` without worrying about - major formatting changes disrupting their project in 2022. We may still - fix bugs where *Black* crashes on some code, and make other improvements - that do not affect formatting. - -- The first release in a new calendar year *may* contain formatting changes, - although these will be minimised as much as possible. This is to allow for - improved formatting enabled by newer Python language syntax as well as due - to improvements in the formatting logic. - -- The ``--preview`` flag is exempt from this policy. There are no guarantees - around the stability of the output with that flag passed into *Black*. This - flag is intended for allowing experimentation with the proposed changes to - the *Black* code style. - -Documentation for both the current and future styles can be found: - -- :doc:`current_style` -- :doc:`future_style` diff --git a/docs/usage_and_configuration/index.md b/docs/usage_and_configuration/index.md new file mode 100644 index 0000000..1c86a49 --- /dev/null +++ b/docs/usage_and_configuration/index.md @@ -0,0 +1,28 @@ +# Usage and Configuration + +```{toctree} +--- +hidden: +--- + +the_basics +file_collection_and_discovery +black_as_a_server +black_docker_image +``` + +Sometimes, running _Black_ with its defaults and passing filepaths to it just won't cut +it. Passing each file using paths will become burdensome, and maybe you would like +_Black_ to not touch your files and just output diffs. And yes, you _can_ tweak certain +parts of _Black_'s style, but please know that configurability in this area is +purposefully limited. + +Using many of these more advanced features of _Black_ will require some configuration. +Configuration that will either live on the command line or in a TOML configuration file. + +This section covers features of _Black_ and configuring _Black_ in detail: + +- {doc}`The basics <./the_basics>` +- {doc}`File collection and discovery ` +- {doc}`Black as a server (blackd) <./black_as_a_server>` +- {doc}`Black Docker image <./black_docker_image>` diff --git a/docs/usage_and_configuration/index.rst b/docs/usage_and_configuration/index.rst deleted file mode 100644 index f6152ee..0000000 --- a/docs/usage_and_configuration/index.rst +++ /dev/null @@ -1,26 +0,0 @@ -Usage and Configuration -======================= - -.. toctree:: - :hidden: - - the_basics - file_collection_and_discovery - black_as_a_server - black_docker_image - -Sometimes, running *Black* with its defaults and passing filepaths to it just won't cut -it. Passing each file using paths will become burdensome, and maybe you would like -*Black* to not touch your files and just output diffs. And yes, you *can* tweak certain -parts of *Black*'s style, but please know that configurability in this area is -purposefully limited. - -Using many of these more advanced features of *Black* will require some configuration. -Configuration that will either live on the command line or in a TOML configuration file. - -This section covers features of *Black* and configuring *Black* in detail: - -- :doc:`The basics <./the_basics>` -- :doc:`File collection and discovery ` -- :doc:`Black as a server (blackd) <./black_as_a_server>` -- :doc:`Black Docker image <./black_docker_image>`