update distributing chapter

1 files changed, 20 insertions, 21 deletions

diff --git a/docs/tutorials/wiki2/distributing.rst b/docs/tutorials/wiki2/distributing.rst
index 0eff63461..08f7d4d48 100644
--- a/docs/tutorials/wiki2/distributing.rst
+++ b/docs/tutorials/wiki2/distributing.rst
@@ -4,37 +4,36 @@
 Distributing Your Application
 =============================
 
-Once your application works properly, you can create a "tarball" from it by
-using the ``setup.py sdist`` command.  The following commands assume your
+.. note::
+
+    This is an optional step.
+    It is not required nor expected that every application is built to be distributed to a package index.
+    However, even when building personal projects, defining it as a distributable artifact can provide many advantages when it comes to optimizing your build for a Docker image or other "production" hardened environments that should not mirror your local development environment exactly.
+
+Once your application works properly, you can create a "sdist" or "wheel" from
+it by using a PEP517-compliant client tool. The following commands assume your
 current working directory contains the ``tutorial`` package and the
-``setup.py`` file.
+``pyproject.toml`` file.
 
 On Unix:
 
 .. code-block:: bash
 
-    $VENV/bin/python setup.py sdist
+    $VENV/bin/pip install build
+    $VENV/bin/python -m build
 
 On Windows:
 
 .. code-block:: doscon
 
-    %VENV%\Scripts\python setup.py sdist
-
-The output of such a command will be something like:
-
-.. code-block:: text
+    %VENV%\Scripts\pip install build
+    %VENV%\Scripts\python -m build
 
-    running sdist
-    # more output
-    creating dist
-    Creating tar archive
-    removing 'tutorial-0.0' (and everything under it)
+Upon successfull completion, a "sdist" and a "wheel" will be output to the ``dist`` subdirectory.
+These artifacts are uploadable to `PyPI <https://pypi.org/>`_ using a tool like ``twine``.
+You should be able to create a brand new virtualenv and ``pip install`` the sdist or wheel.
+Note that the ``production.ini`` is not part of the distribution.
+This file is considered to be defined by the "user" of your application, not part of the application itself.
+If you'd like to help a user out, consider defining a new CLI script that can render a config file for them!
 
-Note that this command creates a tarball in the ``dist`` subdirectory named
-``tutorial-0.0.tar.gz``.  You can send this file to your friends to show them
-your cool new application.  They should be able to install it by pointing the
-``pip install`` command directly at it. Or you can upload it to `PyPI
-<https://pypi.org/>`_ and share it with the rest of the world, where
-it can be downloaded via ``pip install`` remotely like any other package people
-download from PyPI.
+Please learn more about distributing an application from the `Python Packaging User Guide <https://packaging.python.org/en/latest/tutorials/packaging-projects/>`_.