Merge pull request #5436 from pypa/docs-improvements

Docs improvements

docs/conf.py

@@ -170,7 +170,7 @@ latex_documents = [
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "pipenv", "pipenv Documentation", [author], 1)]
+man_pages = [("quickstart", "pipenv", "", [author], 1)]
 
 
 # -- Options for Texinfo output -------------------------------------------

docs/index.rst

@@ -65,10 +65,6 @@ More detailed installation instructions can be found in the :ref:`installing-pip
 ✨🍰✨
 
 .. toctree::
-   :maxdepth: 2
-
-   install
-   changelog
 
 User Testimonials
 -----------------
@@ -91,26 +87,8 @@ User Testimonials
 - Automatically adds/removes packages to a ``Pipfile`` when they are installed or uninstalled.
 - Automatically loads ``.env`` files, if they exist.
 
-The main commands are ``install``, ``uninstall``, and ``lock``, which generates a ``Pipfile.lock``. These are intended to replace ``$ pip install`` usage, as well as manual virtualenv management (to activate a virtualenv, run ``$ pipenv shell``).
-
-Basic Concepts
-//////////////
-
-- A virtualenv will automatically be created, when one doesn't exist.
-- When no parameters are passed to ``install``, all packages ``[packages]`` specified will be installed.
-- To initialize a Python 3 virtual environment, run ``$ pipenv --three``.
-- Otherwise, whatever virtualenv defaults to will be the default.
-
-
-
-Other Commands
-//////////////
-
-- ``graph`` will show you a dependency graph of your installed dependencies.
-- ``shell`` will spawn a shell with the virtualenv activated. This shell can be deactivated by using ``exit``.
-- ``run`` will run a given command from the virtualenv, with any arguments forwarded (e.g. ``$ pipenv run python`` or ``$ pipenv run pip freeze``).
-- ``check`` checks for security vulnerabilities and asserts that `PEP 508 <https://www.python.org/dev/peps/pep-0508/>`_ requirements are being met by the current environment.
 
+.. include:: quickstart.rst
 
 Further Documentation Guides
 ----------------------------
@@ -118,10 +96,12 @@ Further Documentation Guides
 .. toctree::
    :maxdepth: 2
 
+   install
    basics
    advanced
    cli
    diagnose
+   changelog
 
 Contribution Guides
 -------------------

docs/quickstart.rst

@@ -0,0 +1,34 @@
+Basic Commands and Concepts
+///////////////////////////
+
+Pipenv uses a set of commands to manage your Project's dependencies and custom scripts.
+It replaces the use of ``Makefile``, direct calls to ``pip`` and ``python -m venv`` or ``virtualenv``.
+to create virtual environments and install packages in them.
+Pipenv uses two files to do this: ``Pipfile``  and ``Pipfile.lock`` (which will look familiar if you
+are used to packages manager like ``yarn`` or ``npm``).
+
+The main commands are:
+
+- ``install`` -
+
+  Will create a virtual env and install dependencies (if it does not exist already)
+  The dependencies will be installed inside.
+
+- ``install package==0.2`` -
+
+  Will add the package in version 0.2 to the virtual environment and
+  to ``Pipfile`` and ``Pipfile.lock``
+
+- ``uninstall`` - Will remove the dependency
+
+- ``lock`` - Regenarate ``Pipfile.lock`` and updates the dependencies inside it.
+
+These are intended to replace ``$ pip install`` usage, as well as manual virtualenv management.
+
+Other Commands
+//////////////
+
+- ``graph`` will show you a dependency graph of your installed dependencies.
+- ``shell`` will spawn a shell with the virtualenv activated. This shell can be deactivated by using ``exit``.
+- ``run`` will run a given command from the virtualenv, with any arguments forwarded (e.g. ``$ pipenv run python`` or ``$ pipenv run pip freeze``).
+- ``check`` checks for security vulnerabilities and asserts that `PEP 508 <https://www.python.org/dev/peps/pep-0508/>`_ requirements are being met by the current environment.