Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

upgrade the wiki2 tutorial with the new cookiecutter updates #3747

Merged
merged 15 commits into from
Feb 8, 2024
Prev Previous commit
Next Next commit
update distributing chapter
mmerickel committed Feb 5, 2024
commit 3069052018cc1f1dd6dc2ed702b829a1a7147212
41 changes: 20 additions & 21 deletions docs/tutorials/wiki2/distributing.rst
Original file line number Diff line number Diff line change
@@ -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/>`_.