reformat contributing doc

CONTRIBUTING.rst

@@ -3,86 +3,108 @@ How to contribute to Flask
 
 Thank you for considering contributing to Flask!
 
+
 Support questions
 -----------------
 
 Please, don't use the issue tracker for this. Use one of the following
 resources for questions about your own code:
 
-* The ``#get-help`` channel on our Discord chat: https://discordapp.com/invite/t6rrQZH
+-   The ``#get-help`` channel on our Discord chat:
+    https://discord.gg/t6rrQZH
 
-  * The IRC channel ``#pocoo`` on FreeNode is linked to Discord, but
+    -   The IRC channel ``#pocoo`` on FreeNode is linked to Discord, but
-    Discord is preferred.
+        Discord is preferred.
 
-* The mailing list flask@python.org for long term discussion or larger issues.
+-   The mailing list flask@python.org for long term discussion or larger
-* Ask on `Stack Overflow`_. Search with Google first using:
+    issues.
-  ``site:stackoverflow.com flask {search term, exception message, etc.}``
+-   Ask on `Stack Overflow`_. Search with Google first using:
+    ``site:stackoverflow.com flask {search term, exception message, etc.}``
 
 .. _Stack Overflow: https://stackoverflow.com/questions/tagged/flask?sort=linked
 
+
 Reporting issues
 ----------------
 
-- Describe what you expected to happen.
+-   Describe what you expected to happen.
-- If possible, include a `minimal reproducible example`_ to help us
+-   If possible, include a `minimal reproducible example`_ to help us
-  identify the issue. This also helps check that the issue is not with
+    identify the issue. This also helps check that the issue is not with
-  your own code.
+    your own code.
-- Describe what actually happened. Include the full traceback if there was an
+-   Describe what actually happened. Include the full traceback if there
-  exception.
+    was an exception.
-- List your Python, Flask, and Werkzeug versions. If possible, check if this
+-   List your Python, Flask, and Werkzeug versions. If possible, check
-  issue is already fixed in the repository.
+    if this issue is already fixed in the repository.
 
 .. _minimal reproducible example: https://stackoverflow.com/help/minimal-reproducible-example
 
+
 Submitting patches
 ------------------
 
-- Use `Black`_ to autoformat your code. This should be done for you as a
+-   Use `Black`_ to autoformat your code. This should be done for you as
-  git `pre-commit`_ hook, which gets installed when you run ``pip install -e .[dev]``.
+    a Git `pre-commit`_ hook, set up below. You may also wish to use
-  You may also wish to use Black's `Editor integration`_.
+    Black's `Editor integration`_.
-- Include tests if your patch is supposed to solve a bug, and explain
+-   Include tests if your patch is supposed to solve a bug, and explain
-  clearly under which circumstances the bug happens. Make sure the test fails
+    clearly under which circumstances the bug happens. Make sure the
-  without your patch.
+    test fails without your patch.
-- Include a string like "Fixes #123" in your commit message
+-   Include a string like "Fixes #123" in your commit message (where 123
-  (where 123 is the issue you fixed).
+    is the issue you fixed). See `Closing issues using keywords
-  See `Closing issues using keywords
+    <https://help.github.com/articles/creating-a-pull-request/>`__.
-  <https://help.github.com/articles/creating-a-pull-request/>`__.
+
 
 First time setup
 ~~~~~~~~~~~~~~~~
 
-- Download and install the `latest version of git`_.
+-   Download and install the `latest version of git`_.
-- Configure git with your `username`_ and `email`_::
+-   Configure git with your `username`_ and `email`_.
 
-        git config --global user.name 'your name'
+    .. code-block:: text
-        git config --global user.email 'your email'
 
-- Make sure you have a `GitHub account`_.
+        $ git config --global user.name 'your name'
-- Fork Flask to your GitHub account by clicking the `Fork`_ button.
+        $ git config --global user.email 'your email'
-- `Clone`_ your GitHub fork locally::
 
-        git clone https://github.com/{username}/flask
+-   Make sure you have a `GitHub account`_.
-        cd flask
+-   Fork Flask to your GitHub account by clicking the `Fork`_ button.
+-   `Clone`_ your GitHub fork locally.
 
-- Add the main repository as a remote to update later::
+    .. code-block:: text
+
+        $ git clone https://github.com/{username}/flask
+        $ cd flask
+
+-   Add the main repository as a remote to update later::
+
+    .. code-block:: text
 
         git remote add pallets https://github.com/pallets/flask
         git fetch pallets
 
-- Create a virtualenv::
+-   Create a virtualenv.
 
-        python3 -m venv env
+    .. code-block:: text
-        . env/bin/activate
-        # or "env\Scripts\activate" on Windows
 
-- Install Flask in editable mode with development dependencies::
+        $ python3 -m venv env
+        $ . env/bin/activate
 
-        pip install -e ".[dev]"
+    On Windows, activating is different.
 
-- Install the `pre-commit framework`_.
+    .. code-block:: text
-- Install the pre-commit hooks::
 
-        pre-commit install --install-hooks
+        > env\Scripts\activate
+
+-   Install Flask in editable mode with development dependencies.
+
+    .. code-block:: text
+
+        $ pip install -e ".[dev]"
+
+-   Install the `pre-commit framework`_.
+-   Install the pre-commit hooks.
+
+    .. code-block:: text
+
+        $ pre-commit install
 
 .. _GitHub account: https://github.com/join
 .. _latest version of git: https://git-scm.com/downloads
@@ -92,28 +114,35 @@ First time setup
 .. _Clone: https://help.github.com/en/articles/fork-a-repo#step-2-create-a-local-clone-of-your-fork
 .. _pre-commit framework: https://pre-commit.com/#install
 
+
 Start coding
 ~~~~~~~~~~~~
 
 -   Create a branch to identify the issue you would like to work on. If
     you're submitting a bug or documentation fix, branch off of the
-    latest ".x" branch::
+    latest ".x" branch.
 
-        git checkout -b your-branch-name origin/1.0.x
+    .. code-block:: text
+
+        $ git checkout -b your-branch-name origin/1.0.x
 
     If you're submitting a feature addition or change, branch off of the
-    "master" branch::
+    "master" branch.
 
-        git checkout -b your-branch-name origin/master
+    .. code-block:: text
 
-- Using your favorite editor, make your changes, `committing as you go`_.
+        $ git checkout -b your-branch-name origin/master
-- Include tests that cover any code changes you make. Make sure the test fails
-  without your patch. `Run the tests <contributing-testsuite_>`_.
-- Push your commits to GitHub and `create a pull request`_ by using::
 
-        git push --set-upstream origin your-branch-name
+-   Using your favorite editor, make your changes,
+    `committing as you go`_.
+-   Include tests that cover any code changes you make. Make sure the
+    test fails without your patch.
+    `Run the tests <contributing-testsuite_>`_.
+-   Push your commits to GitHub and `create a pull request`_.
 
-- Celebrate 🎉
+    .. code-block:: text
+
+        $ git push --set-upstream origin your-branch-name
 
 .. _committing as you go: https://dont-be-afraid-to-commit.readthedocs.io/en/latest/git/commandlinegit.html#commit-your-changes
 .. _Black: https://black.readthedocs.io
@@ -121,37 +150,43 @@ Start coding
 .. _pre-commit: https://pre-commit.com
 .. _create a pull request: https://help.github.com/en/articles/creating-a-pull-request
 
+
 .. _contributing-testsuite: #running-the-tests
 
 Running the tests
 ~~~~~~~~~~~~~~~~~
 
-Run the basic test suite with::
+Run the basic test suite with pytest.
 
-    pytest
+.. code-block:: text
 
-This only runs the tests for the current environment. Whether this is relevant
+    $ pytest
-depends on which part of Flask you're working on. Travis-CI will run the full
+
-suite when you submit your pull request.
+This only runs the tests for the current environment. Whether this is
+relevant depends on which part of Flask you're working on. CI will run
+the full suite when you submit your pull request.
 
 The full test suite takes a long time to run because it tests multiple
 combinations of Python and dependencies. If you don't have a Python
 version installed, it will be skipped with a warning message at the end.
-Run::
 
-    tox
+.. code-block:: text
+
+    $ tox
+
 
 Running test coverage
 ~~~~~~~~~~~~~~~~~~~~~
 
 Generating a report of lines that do not have test coverage can indicate
-where to start contributing. Run ``pytest`` using ``coverage`` and generate a
+where to start contributing. Run ``pytest`` using ``coverage`` and
-report on the terminal and as an interactive HTML document::
+generate a report on the terminal and as an interactive HTML document.
 
-    coverage run -m pytest
+.. code-block:: text
-    coverage report
+
-    coverage html
+    $ coverage run -m pytest
-    # then open htmlcov/index.html
+    $ coverage report
+    $ coverage html  # then open htmlcov/index.html
 
 Read more about `coverage <https://coverage.readthedocs.io>`_.
 
@@ -162,11 +197,12 @@ from all runs.
 Building the docs
 ~~~~~~~~~~~~~~~~~
 
-Build the docs in the ``docs`` directory using Sphinx::
+Build the docs in the ``docs`` directory using Sphinx.
 
-    cd docs
+.. code-block:: text
-    pip install -r requirements.txt
+
-    make html
+    $ cd docs
+    $ make html
 
 Open ``_build/html/index.html`` in your browser to view the docs.
 
@@ -176,22 +212,23 @@ Read more about `Sphinx <https://www.sphinx-doc.org/en/master/>`_.
 Caution: zero-padded file modes
 -------------------------------
 
-This repository contains several zero-padded file modes that may cause issues
+This repository contains several zero-padded file modes that may cause
-when pushing this repository to git hosts other than GitHub. Fixing this is
+issues when pushing this repository to Git hosts other than GitHub.
-destructive to the commit history, so we suggest ignoring these warnings. If it
+Fixing this is destructive to the commit history, so we suggest ignoring
-fails to push and you're using a self-hosted git service like GitLab, you can
+these warnings. If it fails to push and you're using a self-hosted Git
-turn off repository checks in the admin panel.
+service like GitLab, you can turn off repository checks in the admin
+panel.
 
-These files can also cause issues while cloning. If you have ::
+These files can also cause issues while cloning if you have
+``fsckObjects`` enabled with either of the following in your git config.
+
+.. code-block::
 
     [fetch]
-    fsckobjects = true
+    fsckObjects = true
-
-or ::
 
     [receive]
     fsckObjects = true
 
-set in your git configuration file, cloning this repository will fail. The only
+The only solution is to set both of the above to ``false``, clone, and
-solution is to set both of the above settings to false while cloning, and then
+then set them back to ``true`` after.
-setting them back to true after the cloning is finished.