Fix formatting in /docs (#5721)

docs/docker.md

@@ -58,14 +58,14 @@ doing a multistage build for your application:
     CMD ["./.venv/bin/python", "-m", "run.py"]
 
 ```{note}
-   Pipenv is not meant to run as root. However, in the multistage build above
-   it is done nevertheless. A calculated risk, since the intermediate image
-   is discarded.
-   The runtime image later shows that you should create a user and user it to
-   run your application.
-   **Once again, you should not run pipenv as root (or Admin on Windows) normally.
-   This could lead to breakage of your Python installation, or even your complete
-   OS.**
+Pipenv is not meant to run as root. However, in the multistage build above
+it is done nevertheless. A calculated risk, since the intermediate image
+is discarded.
+The runtime image later shows that you should create a user and user it to
+run your application.
+**Once again, you should not run pipenv as root (or Admin on Windows) normally.
+This could lead to breakage of your Python installation, or even your complete
+OS.**
 ```
 
 When you build an image with this example (assuming requests is found in Pipfile), you

docs/index.md

@@ -24,7 +24,7 @@ The recommended way to install pipenv on most platforms is to install from pypi
 
     $ pip install --user pipenv
 
-More detailed installation instructions can be found in the :ref:`installing-pipenv` chapter.
+More detailed installation instructions can be found in the [installing Pipenv](installation) chapter.
 
 ✨🍰✨
 

docs/indexes.md

@@ -35,14 +35,13 @@ Alternatively the index may be specified by full url, and it will be added to th
 unless it already exists in which case the existing name with be reused when pinning the package index.
 
 ```{note}
-    In prior versions of `pipenv` you could specify `--extra-index-urls` to the `pip` resolver and avoid
-    specifically matching the expected index by name.   That functionality was deprecated in favor of index restricted
-    packages, which is a simplifying assumption that is more security mindful.  The pip documentation has the following
-    warning around the `--extra-index-urls` option:
-
-    Using this option to search for packages which are not in the main repository (such as private packages) is unsafe,
-    per a security vulnerability called dependency confusion: an attacker can claim the package on the public repository
-    in a way that will ensure it gets chosen over the private package.*
+In prior versions of `pipenv` you could specify `--extra-index-urls` to the `pip` resolver and avoid specifically matching the expected index by name.
+That functionality was deprecated in favor of index restricted packages, which is a simplifying assumption that is more security mindful.
+The pip documentation has the following warning around the `--extra-index-urls` option:
+
+> Using this option to search for packages which are not in the main repository (such as private packages) is unsafe,
+> per a security vulnerability called dependency confusion: an attacker can claim the package on the public repository
+> in a way that will ensure it gets chosen over the private package.
 ```
 
 Should you wish to use an alternative default index other than PyPI: simply do not specify PyPI as one of the

docs/installation.md

@@ -1,85 +1,83 @@
 # Pipenv Installation
 
-Note: This guide is written for Python 3.7+
+```{note}
+This guide is written for Python 3.7+
+```
 
 
-## Make sure you have python
+## Make sure you have python and pip
 
 Before you go any further, make sure you have Python and that it's available
-from your command line. You can check this by simply running:
+from your command line. You can check this by simply running
 
     $ python --version
 
 You should get some output like `3.10.8`. If you do not have Python, please
 install the latest 3.x version from [python.org](https://python.org)
 
-Additionally, you will want to make sure you have pip available.
-Check this by running:
+Additionally, make sure you have [pip] available.
+Check this by running
 
     $ pip --version
     pip 22.3.1
 
-If you installed Python from source, with an installer from [python.org], via `Homebrew`_ you likely already have pip.
+If you installed Python from source, with an installer from [python.org] or via [Homebrew], you likely already have pip.
 If you're on Linux and installed using your OS package manager, you may have to [install pip](https://pip.pypa.io/en/stable/installing/) manually.
 
-* [python.org](https://python.org)
-* [Installing Python](https://wiki.python.org/moin/BeginnersGuide/Download)
-* [pip](https://pypi.org/project/pip/)
-
+[python.org]: https://python.org
+[pypi.org]: https://pypi.org
+[pip]: https://pypi.org/project/pip/
+[Homebrew]: https://brew.sh/
 
 
 ## Installing Pipenv
 
-It is recommended that users on most platforms should install pipenv from pypi.org using `pip install pipenv --user`.
-
 
 ### Preferred Installation of Pipenv
 
-If you have a working installation of pip, and maintain certain "tool-chain" type Python modules as global utilities in your user environment, pip `user installs <https://pip.pypa.io/en/stable/user_guide/#user-installs>`_ allow for installation into your home directory. Note that due to interaction between dependencies, you should limit tools installed in this way to basic building blocks for a Python workflow like virtualenv, pipenv, tox, and similar software.
-
-To install:
+It is recommended that users on most platforms install pipenv from [pypi.org] using
 
     $ pip install pipenv --user
 
 ```{note}
-    This does a `user installation`_ to prevent breaking any system-wide
-    packages. If `pipenv` isn't available in your shell after installation,
-    you'll need to add the user site-packages binary directory to your `PATH`.
-
-    On Linux and macOS you can find the user base binary directory by running
-    `python -m site --user-base` and adding `bin` to the end. For example,
-    this will typically print `~/.local` (with `~` expanded to the
-    absolute path to your home directory) so you'll need to add
-    `~/.local/bin` to your `PATH`. You can set your `PATH` permanently by
-    `modifying ~/.profile`_.
-
-    On Windows you can find the user base binary directory by running
-    `python -m site --user-site` and replacing `site-packages` with
-    `Scripts`. For example, this could return
-    `C:\Users\Username\AppData\Roaming\Python37\site-packages` so you would
-    need to set your `PATH` to include
-    `C:\Users\Username\AppData\Roaming\Python37\Scripts`. You can set your
-    user `PATH` permanently in the `Control Panel`_. You may need to log
-    out for the `PATH` changes to take effect.
-
-    For more information, see the `user installs documentation <https://pip.pypa.io/en/stable/user_guide/#user-installs>`_.
+pip [user installations] allow for installation into your home directory to prevent breaking any system-wide packages.
+Due to interaction between dependencies, you should limit tools installed in this way to basic building blocks for a Python workflow such as virtualenv, pipenv, tox, and similar software.
 ```
 
-.. _user base: https://docs.python.org/3/library/site.html#site.USER_BASE
-.. _user installation: https://pip.pypa.io/en/stable/user_guide/#user-installs
-.. _modifying ~/.profile: https://stackoverflow.com/a/14638025
 
+If `pipenv` isn't available in your shell after installation,
+you'll need to add the user site-packages binary directory to your `PATH`.
 
-To upgrade pipenv at any time:
+On Linux and macOS you can find the [user base] binary directory by running
+`python -m site --user-base` and appending `bin` to the end. For example,
+this will typically print `~/.local` (with `~` expanded to the
+absolute path to your home directory), so you'll need to add
+`~/.local/bin` to your `PATH`. You can set your `PATH` permanently by
+[modifying ~/.profile].
 
-    $ pip install --user --upgrade pipenv
+On Windows you can find the user base binary directory by running
+`python -m site --user-site` and replacing `site-packages` with
+`Scripts`. For example, this could return
+`C:\Users\Username\AppData\Roaming\Python37\site-packages`, so you would
+need to set your `PATH` to include
+`C:\Users\Username\AppData\Roaming\Python37\Scripts`. You can set your
+user `PATH` permanently in the [Control Panel](https://learn.microsoft.com/en-us/windows/win32/shell/user-environment-variables).
 
+You may need to log out for the `PATH` changes to take effect.
 
+[user base]: https://docs.python.org/3/library/site.html#site.USER_BASE
+[user installations]: https://pip.pypa.io/en/stable/user_guide/#user-installs
+[modifying ~/.profile]: https://stackoverflow.com/a/14638025
+[Control Panel]: https://learn.microsoft.com/en-us/windows/win32/shell/user-environment-variables
+
+To upgrade pipenv at any time:
+
+    $ pip install --user --upgrade pipenv
 
 ### Homebrew Installation of Pipenv
-* [Homebrew](https://brew.sh) is a popular open-source package management system for macOS. For Linux users, `Linuxbrew`_  is a Linux port of that.
+* [Homebrew] is a popular open-source package management system for macOS (or Linux).
 
-Once you have installed Homebrew or Linuxbrew simply run:
+Once you have installed Homebrew simply run
 
     $ brew install pipenv
 
@@ -88,32 +86,33 @@ To upgrade pipenv at any time:
     $ brew upgrade pipenv
 
 ```{note}
-Homebrew installation is discouraged because it works better to install pipenv using pip on macOS
+Homebrew installation is discouraged because it works better to install pipenv using pip on macOS.
 ```
 
-### Installing packages for your project
+## Installing packages for your project
 
-Pipenv manages dependencies on a per-project basis. To install packages,
+Pipenv manages dependencies on a per-project basis. To install a package,
 change into your project's directory (or just an empty directory for this
-tutorial) and run:
+tutorial) and run
 
     $ cd myproject
-    $ pipenv install requests
+    $ pipenv install <package>
 
 ```{note}
-   Pipenv is designed to be used by non-privileged OS users. It is not meant
-   to install or handle packages for the whole OS. Running Pipenv as `root`
-   or with `sudo` (or `Admin` on Windows) is highly discouraged and might
-   lead to unintend breakage of your OS.
+Pipenv is designed to be used by non-privileged OS users. It is not meant
+to install or handle packages for the whole OS. Running Pipenv as `root`
+or with `sudo` (or `Admin` on Windows) is highly discouraged and might
+lead to unintend breakage of your OS.
 ```
 
-Pipenv will install the `requests` library and create a `Pipfile`
+Pipenv will install the package and create a `Pipfile`
 for you in your project's directory. The `Pipfile` is used to track which
 dependencies your project needs in case you need to re-install them, such as
 when you share your project with others.
 
-You should get output similar to this:
+For example when installing the `requests` library, you should get output similar to this:
 
+    $ pipenv install requests
     Creating a virtualenv for this project...
     Pipfile: C:\Users\matte\Projects\pipenv-triage\example\Pipfile
     Using C:/Users/matte/AppData/Local/Programs/Python/Python311/python.exe (3.11.2) to create virtualenv...

docs/specifiers.md

@@ -30,9 +30,9 @@ To make inclusive or exclusive version comparisons you can use:
     $ pipenv install "requests>2.19"   # will install 2.19.1 but not 2.19.0
 
 ```{note}
-    The use of double quotes around the package and version specification (i.e. `"requests>2.19"`) is highly recommended
-    to avoid issues with `Input and output redirection <https://robots.thoughtbot.com/input-output-redirection-in-the-shell>`_
-    in Unix-based operating systems.
+The use of double quotes around the package and version specification (i.e. `"requests>2.19"`) is highly recommended
+to avoid issues with [Input and output redirection](https://robots.thoughtbot.com/input-output-redirection-in-the-shell)
+in Unix-based operating systems.
 ```
 
 The use of `~=` is preferred over the `==` identifier as the latter prevents pipenv from updating the packages:
@@ -75,9 +75,9 @@ If a `Pipfile` hasn't been created yet, one will be created for you, that looks
     python_version = "3.11"
 
 ```{note}
-   The inclusion of `[requires] python_version = "3.11"` specifies that your application requires this version
-   of Python, and will be used automatically when running `pipenv install` against this `Pipfile` in the future
-   (e.g. on other machines). If this is not true, feel free to simply remove this section.
+The inclusion of `[requires] python_version = "3.11"` specifies that your application requires this version
+of Python, and will be used automatically when running `pipenv install` against this `Pipfile` in the future
+(e.g. on other machines). If this is not true, feel free to simply remove this section.
 ```
 
 If you don't specify a Python version on the command–line, either the `[requires]` `python_full_version` or `python_version` will be selected
@@ -154,11 +154,11 @@ Example usages:
 
 
 ```{note}
-  The `packages`/`default` specifiers are used to constrain all other categories just as they have done
-  for `dev-packages`/`develop` category.  However this is the only way constraints are applied --
-  the presence of other named groups do not constraint each other,
-  which means it is possible to define conflicting package versions across groups.
-  This may be desired in some use cases where users only are installing groups specific to their system platform.
+The `packages`/`default` specifiers are used to constrain all other categories just as they have done
+for `dev-packages`/`develop` category.  However this is the only way constraints are applied --
+the presence of other named groups do not constraint each other,
+which means it is possible to define conflicting package versions across groups.
+This may be desired in some use cases where users only are installing groups specific to their system platform.
 ```
 
 ## Specifying Basically Anything

docs/virtualenv.md

@@ -2,8 +2,8 @@
 
 ## Custom Virtual Environment Location
 
-Pipenv automatically honors the `WORKON_HOME` environment variable, if you
-have it set — so you can tell pipenv to store your virtual environments
+Pipenv automatically honors the `WORKON_HOME` environment variable, if it
+is set, so you can tell pipenv to store your virtual environments
 wherever you want, e.g.:
 
     export WORKON_HOME=~/.venvs
@@ -13,7 +13,7 @@ In addition, you can also have Pipenv stick the virtualenv in `project/.venv` by
 ## Virtual Environment Name
 
 The virtualenv name created by Pipenv may be different from what you were expecting.
-Dangerous characters (i.e. `$`!*@"` as well as space, line feed, carriage return,
+Dangerous characters (i.e. `` $!*@"` ``, as well as space, line feed, carriage return,
 and tab) are converted to underscores. Additionally, the full path to the current
 folder is encoded into a "slug value" and appended to ensure the virtualenv name
 is unique.

docs/workflows.md

@@ -1,42 +1,42 @@
 # Pipenv Workflows
 
-Clone / create project repository::
+Clone / create project repository:
 
     $ cd myproject
 
-Install from `Pipfile.lock`, if there is one::
+Install from `Pipfile.lock`, if there is one:
 
     $ pipenv sync
 
-Add a package to your project, recalibrating entire lock file using the Pipfile specifiers::
+Add a package to your project, recalibrating entire lock file using the Pipfile specifiers:
 
     $ pipenv install <package>
 
 - Note: This will create a `Pipfile` if one doesn't exist. If one does exist, it will automatically be edited with the new package you provided, the lock file updated and the new dependencies installed.
-- `pipenv install` is fully compatible with `pip install` package specifiers, for which the full documentation can be found `here <https://pip.pypa.io/en/stable/user_guide/#installing-packages>`__.
+- `pipenv install` is fully compatible with `pip install` [package specifiers](https://pip.pypa.io/en/stable/user_guide/#installing-packages>).
 - Additional arguments may be supplied to `pip` by supplying `pipenv` with `--extra-pip-args`.
 
-Update everything (equivalent to `pipenv lock && pipenv sync`::
+Update everything (equivalent to `pipenv lock && pipenv sync`):
 
     $ pipenv update
 
-Update and install just the relevant package and its sub-dependencies::
+Update and install just the relevant package and its sub-dependencies:
 
     $ pipenv update <package>
 
-Update in the Pipfile/lockfile just the relevant package and its sub-dependencies::
+Update in the Pipfile/lockfile just the relevant package and its sub-dependencies:
 
     $ pipenv upgrade <package>
 
-Find out what's changed upstream::
+Find out what's changed upstream:
 
     $ pipenv update --outdated
 
-Determine the virtualenv PATH::
+Determine the virtualenv `PATH`:
 
     $ pipenv --venv
 
-Activate the Pipenv shell::
+Activate the Pipenv shell:
 
     $ pipenv shell