Reorganize docs v2 (GH-2174)

[etc/vim.git] / docs / index.rst

diff --git a/docs/index.rst b/docs/index.rst
index f03d247d949a6313adb6d0dfcd50d43d1064807d..a7a7160f71ffa793b305e8ed89ef4a3bc25c9aea 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,12 +14,27 @@ 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>`_.
+Try it out now using the `Black Playground <https://black.vercel.app>`_.
 
-.. note::
+.. admonition:: Note - this is a beta product
+
+   *Black* is already `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.
+   However, *Black* is still beta. Things will probably be wonky for a while. This is
+   made explicit by the "Beta" trove classifier, as well as by the "b" in the versio
+   number. What this means for you is that **until the formatter becomes stable, you
+   should expect some formatting to change in the future**. That being said, no drastic
+   stylistic changes are planned, mostly responses to bug reports.
 
-   `Black is beta <installation_and_usage.html#note-this-is-a-beta-product>`_.
+   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
 ------------
@@ -42,28 +57,62 @@ 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: 2
-
-   installation_and_usage
-   the_black_code_style
-   pyproject_toml
-   compatible_configs
-   editor_integration
-   blackd
-   black_primer
-   version_control_integration
-   github_actions
-   ignoring_unmodified_files
-   contributing_to_black
-   show_your_style
+   :maxdepth: 3
+   :includehidden:
+
+   the_black_code_style/index
+
+.. toctree::
+   :maxdepth: 3
+   :includehidden:
+
+   getting_started
+   usage_and_configuration/index
+   integrations/index
+   guides/index
+
+.. toctree::
+   :maxdepth: 3
+   :includehidden:
+
+   contributing/index
    change_log
-   reference/reference_summary
    authors
 
+.. toctree::
+   :hidden:
+
+   GitHub ↪ <https://github.com/psf/black>
+   PyPI ↪ <https://pypi.org/project/black>
+   IRC ↪ <https://webchat.freenode.net/?channels=%23blackformatter>
+
 Indices and tables
 ==================