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 2801e0eed19bb177e14c65fdf288fd6af6f14e56..e9fdebb55460c7d680ed34502e7bf824c3a1391b 100644 (file)
--- 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 = [
 # 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",
 ]
 
     "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
 # -- 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 (file)
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 (file)
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 <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/guides/index.md b/docs/guides/index.md
new file mode 100644 (file)
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 (file)
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 (file)
index 0000000..9d0db46
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,139 @@
+<!--
+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](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 <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 <https://github.com/psf/black>
+PyPI <https://pypi.org/project/black>
+Chat <https://discord.gg/RtVdv86PrH>
+```
+
+# Indices and tables
+
+- {ref}`genindex`
+- {ref}`search`

diff --git a/docs/index.rst b/docs/index.rst
deleted file mode 100644 (file)
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 <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.html#pragmatism>`_
-   section for details). If you're feeling confident, use ``--fast``.
-
-.. note::
-   :doc:`Black is licensed under the MIT license <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:
-
-.. 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 <https://github.com/psf/black>
-   PyPI <https://pypi.org/project/black>
-   Chat <https://discord.gg/RtVdv86PrH>
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`search`

diff --git a/docs/integrations/index.md b/docs/integrations/index.md
new file mode 100644 (file)
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 (file)
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 <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/license.md b/docs/license.md
new file mode 100644 (file)
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 (file)
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 (file)
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 <current_style>
+Future 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 (file)
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 <current_style>
-    Future 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/usage_and_configuration/index.md b/docs/usage_and_configuration/index.md
new file mode 100644 (file)
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 <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 (file)
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 <file_collection_and_discovery>`
-- :doc:`Black as a server (blackd) <./black_as_a_server>`
-- :doc:`Black Docker image <./black_docker_image>`