Merge pull request #7754 from pradyunsg/docs/consistent-formatting

Consistent formatting across pip's documentation

Author: pradyunsg

.github/ISSUE_TEMPLATE.md

@@ -1,3 +1,3 @@
-* Pip version:
+* pip version:
 * Python version:
 * Operating system:

NEWS.rst

@@ -1538,7 +1538,7 @@ Improved Documentation
   convince some servers who double compress the downloaded file to stop doing
   so. (#1688)
 - Stop breaking when given pip commands in uppercase (#1559, #1725)
-- Pip no longer adds duplicate logging consumers, so it won't create duplicate
+- pip no longer adds duplicate logging consumers, so it won't create duplicate
   output when being called multiple times. (#1618, #1723)
 - `pip wheel` now returns an error code if any wheels fail to build. (#1769)
 - `pip wheel` wasn't building wheels for dependencies of editable requirements.
@@ -1661,7 +1661,7 @@ Improved Documentation
 - pip will now install Mac OSX platform wheels from PyPI. (:pull:`1278`)
 - pip now generates the appropriate platform-specific console scripts when
   installing wheels. (#1251)
-- Pip now confirms a wheel is supported when installing directly from a path or
+- pip now confirms a wheel is supported when installing directly from a path or
   url. (#1315)
 - ``--ignore-installed`` now behaves again as designed, after it was
   unintentionally broke in v0.8.3 when fixing #14. (#1097, #1352)
@@ -1870,7 +1870,7 @@ Improved Documentation
   Dan Callahan for report and patch. (#182)
 - Understand version tags without minor version ("py3") in sdist filenames.
   Thanks Stuart Andrews for report and Olivier Girardot for patch. (#310)
-- Pip now supports optionally installing setuptools "extras" dependencies; e.g.
+- pip now supports optionally installing setuptools "extras" dependencies; e.g.
   "pip install Paste[openid]". Thanks Matt Maker and Olivier Girardot. (#7)
 - freeze no longer borks on requirements files with --index-url or --find-links.
   Thanks Herbert Pfennig. (#391)
@@ -1995,7 +1995,7 @@ Improved Documentation
 
 - Track which ``build/`` directories pip creates, never remove directories
   it doesn't create.  From Hugo Lopes Tavares.
-- Pip now accepts file:// index URLs. Thanks Dave Abrahams.
+- pip now accepts file:// index URLs. Thanks Dave Abrahams.
 - Various cleanup to make test-running more consistent and less fragile.
   Thanks Dave Abrahams.
 - Real Windows support (with passing tests). Thanks Dave Abrahams.

docs/html/cookbook.rst

@@ -1,7 +1,7 @@
 :orphan:
 
-============
+========
 Cookbook
-============
+========
 
 This content is now covered in the :doc:`User Guide <user_guide>`

docs/html/development/architecture/anatomy.rst

@@ -1,4 +1,5 @@
 .. note::
+
     This section of the documentation is currently being written. pip
     developers welcome your help to complete this documentation. If you're
     interested in helping out, please let us know in the `tracking issue`_.
@@ -76,7 +77,7 @@ Within ``src/``:
   * ``__init__.py``
   * ``__main__.py``
   * ``__pycache__/`` *[not discussing contents right now]*
-  * ``_internal/`` *[where all the pip code lives that’s written by pip maintainers -- underscore means private. Pip is not a library -- it’s a command line tool! A very important distinction! People who want to install stuff with pip should not use the internals -- they should use the CLI. There’s a note on this in the docs.]*
+  * ``_internal/`` *[where all the pip code lives that’s written by pip maintainers -- underscore means private. pip is not a library -- it’s a command line tool! A very important distinction! People who want to install stuff with pip should not use the internals -- they should use the CLI. There’s a note on this in the docs.]*
 
     * ``__init__.py``
     * ``build_env.py`` [not discussing now]

docs/html/development/architecture/index.rst

@@ -3,11 +3,13 @@ Architecture of pip's internals
 ===============================
 
 .. note::
+
     This section of the documentation is currently being written. pip
     developers welcome your help to complete this documentation. If you're
     interested in helping out, please let us know in the `tracking issue`_.
 
 .. note::
+
     Direct use of pip's internals is *not supported*, and these internals
     can change at any time. For more details, see :ref:`Using pip from
     your program`.

docs/html/development/architecture/overview.rst

@@ -1,4 +1,5 @@
 .. note::
+
     This section of the documentation is currently being written. pip
     developers welcome your help to complete this documentation. If you're
     interested in helping out, please let us know in the `tracking issue`_.
@@ -9,7 +10,7 @@
 Broad functionality overview
 ****************************
 
-Pip is a package installer.
+pip is a package installer.
 
 pip does a lot more than installation; it also has a cache, and it has
 configuration, and it has a CLI, which has its own quirks. But mainly:
@@ -52,7 +53,7 @@ In sequence, what does pip do?:
 
 4. Install the actual items to be installed.
 
-Why? Pip installs from places other than PyPI! But also, we’ve never had
+Why? pip installs from places other than PyPI! But also, we’ve never had
 guarantees of PyPI’s JSON API before now, so no one has been getting
 metadata from PyPI separate from downloading the package itself.
 
@@ -117,7 +118,7 @@ When pip looks at the package index, the place where it looks has
 basically a link. The link’s text is the name of the file
 
 This is the `PyPI Simple API`_ (PyPI has several APIs, some are being
-deprecated). Pip looks at Simple API, documented initially at :pep:`503` --
+deprecated). pip looks at Simple API, documented initially at :pep:`503` --
 packaging.python.org has PyPA specifications with more details for
 Simple Repository API
 

docs/html/development/architecture/upgrade-options.rst

@@ -1,12 +1,14 @@
+=============================================
 Options that control the installation process
----------------------------------------------
+=============================================
 
 When installing packages, pip chooses a distribution file, and installs it in
 the user's environment. There are many choices involved in deciding which file
 to install, and these are controlled by a variety of options.
 
+
 Controlling what gets installed
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+===============================
 
 These options directly affect how the resolver uses the list of available
 distribution files to decide which one to install. So these modify the
@@ -51,8 +53,9 @@ current version in place. This occurs even if ``--upgrade`` is not set.
 Act as if the currently installed version isn't there - so don't care about
 ``--upgrade``, and don't uninstall before (re-)installing.
 
+
 Controlling what gets considered
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+================================
 
 These options affect the list of distribution files that the resolver will
 consider as candidates for installation. As such, they affect the data that
@@ -89,8 +92,9 @@ Index options
 
 ``--find-links``
 
+
 Controlling dependency data
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+===========================
 
 These options control what dependency data the resolver sees for any given
 package (or, in the case of ``--python-version``, the environment information
@@ -102,8 +106,9 @@ the resolver uses to *check* the dependency).
 
 ``--ignore-requires-python``
 
+
 Special cases
-~~~~~~~~~~~~~
+=============
 
 These need further investigation. They affect the install process, but not
 necessarily resolution or what gets installed.

docs/html/development/ci.rst

@@ -1,13 +1,14 @@
 .. note::
+
     This section of the documentation is currently being written. pip
     developers welcome your help to complete this documentation. If you're
     interested in helping out, please let us know in the `tracking issue`_.
 
 .. _`tracking issue`: https://github.com/pypa/pip/issues/7279
 
-**********************
+======================
 Continuous Integration
-**********************
+======================
 
 Supported interpreters
 ======================
@@ -56,6 +57,7 @@ specified it's ok to require the latest CPython interpreter.
 So only unit tests and integration tests would need to be run with the different
 interpreters.
 
+
 Services
 ========
 

docs/html/development/configuration.rst

@@ -1,5 +1,6 @@
 :orphan:
 
+=============
 Configuration
 =============
 

docs/html/development/contributing.rst

@@ -34,6 +34,7 @@ Examples include re-flowing text in comments or documentation, or addition or
 removal of blank lines or whitespace within lines. Such changes can be made
 separately, as a "formatting cleanup" PR, if needed.
 
+
 Automated Testing
 =================