diff options
| author | eacheson <eacheson@users.noreply.github.com> | 2021-12-24 12:03:44 +0100 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2021-12-24 12:03:44 +0100 |
| commit | 4834907218be6f104cac123caaf87c5d341e1683 (patch) | |
| tree | 623efd7142751fca1900fe10ee3a8071656fafa4 | |
| parent | 247de8a2fbb2d1c34369ee83588100dbbe5f82a2 (diff) | |
| download | python-setuptools-git-4834907218be6f104cac123caaf87c5d341e1683.tar.gz | |
Update quickstart.rst
fix various english issues
| -rw-r--r-- | docs/userguide/quickstart.rst | 26 |
1 files changed, 13 insertions, 13 deletions
diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 98e34c19..da904bab 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -14,9 +14,9 @@ Python packaging at a glance ============================ The landscape of Python packaging is shifting and ``Setuptools`` has evolved to only provide backend support, no longer being the de-facto packaging tool in -the market. All python package must provide a ``pyproject.toml`` and specify +the market. Every python package must provide a ``pyproject.toml`` and specify the backend (build system) it wants to use. The distribution can then -be generated with whatever tools that provides a ``build sdist``-alike +be generated with whatever tool that provides a ``build sdist``-like functionality. While this may appear cumbersome, given the added pieces, it in fact tremendously enhances the portability of your package. The change is driven under :pep:`PEP 517 <517#build-requirements>`. To learn more about Python packaging in general, @@ -76,7 +76,7 @@ This is what your project would look like:: setup.cfg # or setup.py mypackage/__init__.py -Then, you need an builder, such as :std:doc:`PyPA build <pypa-build:index>` +Then, you need a builder, such as :std:doc:`PyPA build <pypa-build:index>` which you can obtain via ``pip install build``. After downloading it, invoke the builder:: @@ -89,15 +89,15 @@ Of course, before you release your project to PyPI, you'll want to add a bit more information to your setup script to help people find or learn about your project. And maybe your project will have grown by then to include a few dependencies, and perhaps some data files and scripts. In the next few sections, -we will walk through those additional but essential information you need +we will walk through the additional but essential information you need to specify to properly package your project. Automatic package discovery =========================== For simple projects, it's usually easy enough to manually add packages to -the ``packages`` keyword in ``setup.cfg``. However, for very large projects -, it can be a big burden to keep the package list updated. ``setuptools`` +the ``packages`` keyword in ``setup.cfg``. However, for very large projects, +it can be a big burden to keep the package list updated. ``setuptools`` therefore provides two convenient tools to ease the burden: :literal:`find:\ ` and :literal:`find_namespace:\ `. To use it in your project: @@ -110,11 +110,11 @@ therefore provides two convenient tools to ease the burden: :literal:`find:\ ` a include=pkg1, pkg2 exclude=pk3, pk4 -When you pass the above information, alongside other necessary ones, +When you pass the above information, alongside other necessary information, ``setuptools`` walks through the directory specified in ``where`` (omitted -here as the package reside in current directory) and filters the packages -it can find following the ``include`` (default to none), then remove -those that match the ``exclude`` and return a list of Python packages. Note +here as the package resides in the current directory) and filters the packages +it can find following the ``include`` (defaults to none), then removes +those that match the ``exclude`` and returns a list of Python packages. Note that each entry in the ``[options.packages.find]`` is optional. The above setup also allows you to adopt a ``src/`` layout. For more details and advanced use, go to :ref:`package_discovery` @@ -122,7 +122,7 @@ use, go to :ref:`package_discovery` Entry points and automatic script creation =========================================== -Setuptools support automatic creation of scripts upon installation, that runs +Setuptools supports automatic creation of scripts upon installation, that runs code within your package if you specify them with the ``entry_points`` keyword. This is what allows you to run commands like ``pip install`` instead of having to type ``python -m pip install``. To accomplish this, add the entry_points @@ -157,7 +157,7 @@ operators <, >, <=, >=, == or !=, followed by a version identifier): When your project is installed, all of the dependencies not already installed will be located (via PyPI), downloaded, built (if necessary), and installed. -This, of course, is a simplified scenarios. ``setuptools`` also provide +This, of course, is a simplified scenarios. ``setuptools`` also provides additional keywords such as ``setup_requires`` that allows you to install dependencies before running the script, and ``extras_require`` that take care of those needed by automatically generated scripts. It also provides @@ -207,7 +207,7 @@ associate with your source code. For more information, see :doc:`development_mod Uploading your package to PyPI ============================== -After generating the distribution files, next step would be to upload your +After generating the distribution files, the next step would be to upload your distribution so others can use it. This functionality is provided by `twine <https://pypi.org/project/twine/>`_ and we will only demonstrate the basic use here. |
