From 73e379cc55ac1e9ec63c4ac30b75ecc82418f513 Mon Sep 17 00:00:00 2001 From: "Jason R. Coombs" Date: Wed, 23 Sep 2020 20:29:14 -0400 Subject: Use canonical extension for docs. --- docs/userguide/quickstart.rst | 210 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 210 insertions(+) create mode 100644 docs/userguide/quickstart.rst (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst new file mode 100644 index 00000000..52829751 --- /dev/null +++ b/docs/userguide/quickstart.rst @@ -0,0 +1,210 @@ +========================== +``setuptools`` Quickstart +========================== + +.. contents:: + +Installation +============ + +To install the latest version of setuptools, use:: + + pip install --upgrade setuptools + + +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 backend (build system) it wants to use. The distribution can then +be generated with whatever tools that provides a ``build sdist``-alike +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 517 ``. To learn more about Python packaging in general, +navigate to the `bottom `_ of this page. + + +Basic Use +========= +For basic use of setuptools, you will need a ``pyproject.toml`` with the +exact following info, which declares you want to use ``setuptools`` to +package your project: + +.. code-block:: toml + + [build-system] + requires = ["setuptools", "wheel"] + build-backend = "setuptools.build_meta" + +Then, you will need a ``setup.cfg`` to specify your package information, +such as metadata, contents, dependencies, etc. Here we demonstrate the minimum + +.. code-block:: ini + + [metadata] + name = "mypackage" + version = 0.0.1 + + [options] + packages = "mypackage" + install_requires = + requests + importlib; python_version == "2.6" + +This is what your project would look like:: + + ~/mypackage/ + pyproject.toml + setup.cfg + mypackage/__init__.py + +Then, you need an installer, such as `pep517 `_ +which you can obtain via ``pip install pep517``. After downloading it, invoke +the installer:: + + python -m pep517.build + +You now have your distribution ready (e.g. a ``tar.gz`` file and a ``.whl`` +file in the ``dist`` directory), which you can upload to PyPI! + +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 section, +we will walk through those 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`` +therefore provides two convenient tools to ease the burden: ``find: `` and +``find_namespace: ``. To use it in your project: + +.. code-block:: ini + + [options] + packages = find: + + [options.packages.find] #optional + include=pkg1, pkg2 + exclude=pk3, pk4 + +When you pass the above information, alongside other necessary ones, +``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 +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` + + +Entry points and automatic script creation +=========================================== +Setuptools support automatic creation of scripts upon installation, that runs +code within your package if you specify them with the ``entry_point`` 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 +keyword in your ``setup.cfg``: + +.. code-block:: ini + + [options] + entry_points = + [console_script] + main = mypkg:some_func + +When this project is installed, a ``main`` script will be installed and will +invoke the ``some_func`` in the ``__init__.py`` file when called by the user. +For detailed usage, including managing the additional or optional dependencies, +go to :ref:`entry_point`. + + +Dependency management +===================== +``setuptools`` supports automatically installing dependencies when a package is +installed. The simplest way to include requirement specifiers is to use the +``install_requires`` argument to ``setup.cfg``. It takes a string or list of +strings containing requirement specifiers (A version specifier is one of the +operators <, >, <=, >=, == or !=, followed by a version identifier): + +.. code-block:: ini + + [options] + install_requires = + docutils >= 0.3 + requests <= 0.4 + +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 +additional keywords such as ``setup_requires`` that allows you to install +dependencies before running the script, and ``extras_requires`` that take +care of those needed by automatically generated scripts. It also provides +mechanisms to handle dependencies that are not in PyPI. For more advanced use, +see :ref:`dependency_management` + + +Including Data Files +==================== +The distutils have traditionally allowed installation of "data files", which +are placed in a platform-specific location. Setuptools offers three ways to +specify data files to be included in your packages. For the simpliest use, you +can simply use the ``include_package_data`` keyword: + +.. code-block:: ini + + [options] + include_package_data = True + +This tells setuptools to install any data files it finds in your packages. +The data files must be specified via the distutils' ``MANIFEST.in`` file. +For more details, see :ref:`datafiles` + + +Development mode +================ +``setuptools`` allows you to install a package without copying any files +to your interpretor directory (e.g. the ``site-packages`` directory). This +allows you to modify your source code and have the changes take effect without +you having to rebuild and reinstall. This is currently incompatible with +PEP 517 and therefore it requires a ``setup.py`` script with the following +content:: + + import setuptools + setuptools.setup() + +Then:: + + pip install --editable . + +This creates a link file in your interpretor site package directory which +associate with your source code. For more information, see: (WIP) + + +Uploading your package to PyPI +============================== +After generating the distribution files, next step would be to upload your +distribution so others can use it. This functionality is provided by +``twine `` and we will only demonstrate the +basic use here. + + +Transitioning from ``setup.py`` to ``setup.cfg`` +================================================== +To avoid executing arbitary scripts and boilerplate code, we are transitioning +into a full-fledged ``setup.cfg`` to declare your package information instead +of running ``setup()``. This inevitably brings challenges due to a different +syntax. Here we provide a quick guide to understanding how ``setup.cfg`` is +parsed by ``setuptool`` to ease the pain of transition. + + +Resources on Python packaging +============================= +Packaging in Python is hard. Here we provide a list of links for those that +want to learn more. -- cgit v1.2.1 From 6722c069db857991b95fb95a5ddf90ec4913094a Mon Sep 17 00:00:00 2001 From: Marius Gedminas Date: Mon, 5 Oct 2020 09:52:31 +0300 Subject: Fix ReST syntax error in the PEP 517 link --- docs/userguide/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 52829751..37d33b26 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -22,7 +22,7 @@ be generated with whatever tools that provides a ``build sdist``-alike 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 517 ``. To learn more about Python packaging in general, +build-requirements>`_. To learn more about Python packaging in general, navigate to the `bottom `_ of this page. -- cgit v1.2.1 From f516f011b0361a329304c3ed6dc611fc97053e2b Mon Sep 17 00:00:00 2001 From: Marius Gedminas Date: Mon, 5 Oct 2020 17:56:12 +0300 Subject: And another malformed link --- docs/userguide/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 37d33b26..3af6d566 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -191,7 +191,7 @@ Uploading your package to PyPI ============================== After generating the distribution files, next step would be to upload your distribution so others can use it. This functionality is provided by -``twine `` and we will only demonstrate the +`twine `_ and we will only demonstrate the basic use here. -- cgit v1.2.1 From b66e45a90e82c9170cc48f21e4dac9d206193953 Mon Sep 17 00:00:00 2001 From: Marius Gedminas Date: Mon, 12 Oct 2020 16:42:51 +0300 Subject: Use the :pep: role instead of a manual link Co-Authored-By: Sviatoslav Sydorenko --- docs/userguide/quickstart.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 3af6d566..a07afae7 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -21,8 +21,8 @@ the backend (build system) it wants to use. The distribution can then be generated with whatever tools that provides a ``build sdist``-alike 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 517 `_. To learn more about Python packaging in general, +change is driven under :pep:`PEP 517 <517#build-requirements>`_. +To learn more about Python packaging in general, navigate to the `bottom `_ of this page. -- cgit v1.2.1 From edfa441febf6c5d8af8973ce952b3a0c19b7b575 Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Fri, 16 Oct 2020 01:14:51 +0200 Subject: =?UTF-8?q?=F0=9F=93=9D=20Recover=20interdoc=20links=20&=20correct?= =?UTF-8?q?=20broken=20syntax?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/userguide/quickstart.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 52829751..3ee4fc8c 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -82,8 +82,8 @@ 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`` -therefore provides two convenient tools to ease the burden: ``find: `` and -``find_namespace: ``. To use it in your project: +therefore provides two convenient tools to ease the burden: :literal:`find:\ ` and +:literal:`find_namespace:\ `. To use it in your project: .. code-block:: ini @@ -122,7 +122,7 @@ keyword in your ``setup.cfg``: When this project is installed, a ``main`` script will be installed and will invoke the ``some_func`` in the ``__init__.py`` file when called by the user. For detailed usage, including managing the additional or optional dependencies, -go to :ref:`entry_point`. +go to :doc:`entry_point`. Dependency management @@ -147,9 +147,11 @@ additional keywords such as ``setup_requires`` that allows you to install dependencies before running the script, and ``extras_requires`` that take care of those needed by automatically generated scripts. It also provides mechanisms to handle dependencies that are not in PyPI. For more advanced use, -see :ref:`dependency_management` +see :doc:`dependency_management` +.. _Including Data Files: + Including Data Files ==================== The distutils have traditionally allowed installation of "data files", which @@ -164,7 +166,7 @@ can simply use the ``include_package_data`` keyword: This tells setuptools to install any data files it finds in your packages. The data files must be specified via the distutils' ``MANIFEST.in`` file. -For more details, see :ref:`datafiles` +For more details, see :doc:`datafiles` Development mode -- cgit v1.2.1 From 883f33613572e3c92021b58522b54958b00cdc87 Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Fri, 16 Oct 2020 01:13:03 +0200 Subject: =?UTF-8?q?=E2=9C=A8Make=20the=20default=20implicit=20role=20autof?= =?UTF-8?q?ind=20targets?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/userguide/quickstart.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 3ee4fc8c..24ea3e4b 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -21,8 +21,7 @@ the backend (build system) it wants to use. The distribution can then be generated with whatever tools that provides a ``build sdist``-alike 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 517 ``. To learn more about Python packaging in general, +change is driven under :pep:`517 <517#build-requirements>`. To learn more about Python packaging in general, navigate to the `bottom `_ of this page. -- cgit v1.2.1 From 9ab7bc54cf1eb1a0cb088e8157dc8c88c553b9c7 Mon Sep 17 00:00:00 2001 From: "Jason R. Coombs" Date: Sat, 17 Oct 2020 13:14:24 -0400 Subject: Clean up syntax on entry_points.console_scripts. Fixes #2429. --- docs/userguide/quickstart.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index aebcf60f..697087ed 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -106,16 +106,15 @@ use, go to :ref:`package_discovery` Entry points and automatic script creation =========================================== Setuptools support automatic creation of scripts upon installation, that runs -code within your package if you specify them with the ``entry_point`` keyword. +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 keyword in your ``setup.cfg``: .. code-block:: ini - [options] - entry_points = - [console_script] + [options.entry_points] + console_scripts = main = mypkg:some_func When this project is installed, a ``main`` script will be installed and will -- cgit v1.2.1 From 0e1fc1c6318864ab70dc0868762e02fa8faaaf8e Mon Sep 17 00:00:00 2001 From: Marius Gedminas Date: Mon, 19 Oct 2020 10:06:57 +0300 Subject: s/517/PEP 517/ --- docs/userguide/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 697087ed..874ac086 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -21,7 +21,7 @@ the backend (build system) it wants to use. The distribution can then be generated with whatever tools that provides a ``build sdist``-alike 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:`517 <517#build-requirements>`. To learn more about Python packaging in general, +change is driven under :pep:`PEP 517 <517#build-requirements>`. To learn more about Python packaging in general, navigate to the `bottom `_ of this page. -- cgit v1.2.1 From d7170a28dc3ad02eacc69d1c425bb6f1d5afe619 Mon Sep 17 00:00:00 2001 From: Greg Solon Date: Tue, 20 Oct 2020 21:55:56 +0800 Subject: Update quickstart.rst Removed quotes in setup.cfg which caused build to fail. --- docs/userguide/quickstart.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 697087ed..a9cb76a4 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -43,11 +43,11 @@ such as metadata, contents, dependencies, etc. Here we demonstrate the minimum .. code-block:: ini [metadata] - name = "mypackage" + name = mypackage version = 0.0.1 [options] - packages = "mypackage" + packages = mypackage install_requires = requests importlib; python_version == "2.6" -- cgit v1.2.1 From b20d12e1fb7132fada3e6b58ec1c1c0bd409c5f7 Mon Sep 17 00:00:00 2001 From: Harald Korneliussen Date: Wed, 18 Nov 2020 19:32:18 +0100 Subject: Fixes syntax issues in quickstart (#2448) Quotes in the name and packages field causes an "Invalid distribution name or version syntax" if you follow this quickstart guide directly. pep517.build also requires you to specify the directory. --- docs/userguide/quickstart.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 697087ed..50a984ec 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -43,11 +43,11 @@ such as metadata, contents, dependencies, etc. Here we demonstrate the minimum .. code-block:: ini [metadata] - name = "mypackage" + name = mypackage version = 0.0.1 [options] - packages = "mypackage" + packages = mypackage install_requires = requests importlib; python_version == "2.6" @@ -63,7 +63,7 @@ Then, you need an installer, such as `pep517 ` which you can obtain via ``pip install pep517``. After downloading it, invoke the installer:: - python -m pep517.build + python -m pep517.build . You now have your distribution ready (e.g. a ``tar.gz`` file and a ``.whl`` file in the ``dist`` directory), which you can upload to PyPI! -- cgit v1.2.1 From 9008e48a54bde1cbbabaf4423906630a4edab877 Mon Sep 17 00:00:00 2001 From: Matt Deitke Date: Sun, 13 Dec 2020 20:42:20 -0800 Subject: typo --- docs/userguide/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 30989826..1d557d47 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -71,7 +71,7 @@ file in the ``dist`` directory), which you can upload to PyPI! 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 section, +dependencies, and perhaps some data files and scripts. In the next few sections, we will walk through those additional but essential information you need to specify to properly package your project. -- cgit v1.2.1 From 80c11d910346ab7df8349cb54c7b9227664fe3e7 Mon Sep 17 00:00:00 2001 From: Pradyun Gedam Date: Mon, 28 Dec 2020 17:49:26 +0000 Subject: Drop table of contents from pages This is included in the sidebar, as part of Furo. --- docs/userguide/quickstart.rst | 2 -- 1 file changed, 2 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 1d557d47..aa09e54d 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -2,8 +2,6 @@ ``setuptools`` Quickstart ========================== -.. contents:: - Installation ============ -- cgit v1.2.1 From e70c2afc1868a7d9bb2e2887ebf19f6c84dcf283 Mon Sep 17 00:00:00 2001 From: Andrey Bienkowski Date: Tue, 9 Feb 2021 09:20:47 +0300 Subject: quickstart: recommend PyPA build instead of pep517.build see https://github.com/pypa/pep517/issues/91 --- docs/userguide/quickstart.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 1d557d47..e7594ba3 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -59,11 +59,11 @@ This is what your project would look like:: setup.cfg mypackage/__init__.py -Then, you need an installer, such as `pep517 `_ -which you can obtain via ``pip install pep517``. After downloading it, invoke +Then, you need an installer, such as :std:doc:`PyPA build ` +which you can obtain via ``pip install build``. After downloading it, invoke the installer:: - python -m pep517.build . + python -m build You now have your distribution ready (e.g. a ``tar.gz`` file and a ``.whl`` file in the ``dist`` directory), which you can upload to PyPI! -- cgit v1.2.1 From 8307bd497dba77f5ef40f504842e023334eba04b Mon Sep 17 00:00:00 2001 From: "Jason R. Coombs" Date: Sun, 28 Feb 2021 16:50:09 -0500 Subject: Term is builder. --- docs/userguide/quickstart.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index e7594ba3..75dc302f 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -59,9 +59,9 @@ This is what your project would look like:: setup.cfg mypackage/__init__.py -Then, you need an installer, such as :std:doc:`PyPA build ` +Then, you need an builder, such as :std:doc:`PyPA build ` which you can obtain via ``pip install build``. After downloading it, invoke -the installer:: +the builder:: python -m build -- cgit v1.2.1 From 474f833a1181ca07b17fe4c52a9680c70335181e Mon Sep 17 00:00:00 2001 From: Amy Date: Sun, 28 Feb 2021 23:07:47 -0500 Subject: Replace adjacent code blocks with tabbed containers --- docs/userguide/quickstart.rst | 43 +++++++++++++++++++++++++++++++------------ 1 file changed, 31 insertions(+), 12 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 1d557d47..16cd4f71 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -37,26 +37,45 @@ package your project: requires = ["setuptools", "wheel"] build-backend = "setuptools.build_meta" -Then, you will need a ``setup.cfg`` to specify your package information, -such as metadata, contents, dependencies, etc. Here we demonstrate the minimum +Then, you will need a ``setup.cfg`` or ``setup.py`` to specify your package +information, such as metadata, contents, dependencies, etc. Here we demonstrate +the minimum -.. code-block:: ini +.. tab:: setup.cfg - [metadata] - name = mypackage - version = 0.0.1 + .. code-block:: ini - [options] - packages = mypackage - install_requires = - requests - importlib; python_version == "2.6" + [metadata] + name = mypackage + version = 0.0.1 + + [options] + packages = mypackage + install_requires = + requests + importlib; python_version == "2.6" + +.. tab:: setup.py + + .. code-block:: python + + from setuptools import setup + + setup( + name='mypackage"' + version='0.0.1', + packages=['mypackage'], + install_requires=[ + 'requests', + 'importlib; python_version == "2.6"', + ], + ) This is what your project would look like:: ~/mypackage/ pyproject.toml - setup.cfg + setup.cfg # or setup.py mypackage/__init__.py Then, you need an installer, such as `pep517 `_ -- cgit v1.2.1 From 07d5e663650f594288dda1c92f2cda010a2a899b Mon Sep 17 00:00:00 2001 From: "T. Wouters" Date: Mon, 29 Mar 2021 15:02:41 +0200 Subject: Fix typo in setup.py example in quickstart guide. --- docs/userguide/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 7f111dd5..4ee59098 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -62,7 +62,7 @@ the minimum from setuptools import setup setup( - name='mypackage"' + name='mypackage' version='0.0.1', packages=['mypackage'], install_requires=[ -- cgit v1.2.1 From c91153a1bf73ceb65efd611603edf638a996f720 Mon Sep 17 00:00:00 2001 From: "T. Wouters" Date: Mon, 29 Mar 2021 15:10:26 +0200 Subject: Update quickstart.rst --- docs/userguide/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 4ee59098..2807f59b 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -62,7 +62,7 @@ the minimum from setuptools import setup setup( - name='mypackage' + name='mypackage', version='0.0.1', packages=['mypackage'], install_requires=[ -- cgit v1.2.1 From f42783143ccf803987e2ee82ee3ba12a26a31e01 Mon Sep 17 00:00:00 2001 From: Carlton Gibson Date: Sat, 10 Apr 2021 10:23:44 +0200 Subject: Fixed quickstart packaging resources hyperlink. The implicit link target that should have been created from the title was not being detected correctly. This was causing the link to be interpreted as an external hyperlink reference, resulting in a 404 in the rendered docs. Adding the explicit target and `ref` allows the link to resolve correctly. --- docs/userguide/quickstart.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 2807f59b..53810526 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -22,7 +22,7 @@ be generated with whatever tools that provides a ``build sdist``-alike 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, -navigate to the `bottom `_ of this page. +navigate to the :ref:`bottom ` of this page. Basic Use @@ -215,13 +215,14 @@ basic use here. Transitioning from ``setup.py`` to ``setup.cfg`` -================================================== +================================================ To avoid executing arbitary scripts and boilerplate code, we are transitioning into a full-fledged ``setup.cfg`` to declare your package information instead of running ``setup()``. This inevitably brings challenges due to a different syntax. Here we provide a quick guide to understanding how ``setup.cfg`` is parsed by ``setuptool`` to ease the pain of transition. +.. _packaging-resources: Resources on Python packaging ============================= -- cgit v1.2.1 From 6f727262240e35e315a66ec0bbb845ad718be127 Mon Sep 17 00:00:00 2001 From: Carlton Gibson Date: Mon, 12 Apr 2021 20:39:54 +0200 Subject: Corrected indent in setup.cfg example. --- docs/userguide/quickstart.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 2807f59b..7435d842 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -52,8 +52,8 @@ the minimum [options] packages = mypackage install_requires = - requests - importlib; python_version == "2.6" + requests + importlib; python_version == "2.6" .. tab:: setup.py -- cgit v1.2.1 From dda5620ffae39d23dc303284d28fe693ff5e7b25 Mon Sep 17 00:00:00 2001 From: Carlton Gibson Date: Mon, 10 May 2021 09:31:57 +0200 Subject: Corrected tabs for spaces in quickstart example. --- docs/userguide/quickstart.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index a9f0bbae..69400450 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -52,8 +52,8 @@ the minimum [options] packages = mypackage install_requires = - requests - importlib; python_version == "2.6" + requests + importlib; python_version == "2.6" .. tab:: setup.py -- cgit v1.2.1 From c063b3af1ecbcea0f0cc63b941f5e2038be9efcb Mon Sep 17 00:00:00 2001 From: luz paz Date: Fri, 14 May 2021 08:34:17 -0400 Subject: Fix misc. doc typos Found via `codespell` --- docs/userguide/quickstart.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index a9f0bbae..5d4dd37b 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -173,7 +173,7 @@ Including Data Files ==================== The distutils have traditionally allowed installation of "data files", which are placed in a platform-specific location. Setuptools offers three ways to -specify data files to be included in your packages. For the simpliest use, you +specify data files to be included in your packages. For the simplest use, you can simply use the ``include_package_data`` keyword: .. code-block:: ini @@ -189,7 +189,7 @@ For more details, see :doc:`datafiles` Development mode ================ ``setuptools`` allows you to install a package without copying any files -to your interpretor directory (e.g. the ``site-packages`` directory). This +to your interpreter directory (e.g. the ``site-packages`` directory). This allows you to modify your source code and have the changes take effect without you having to rebuild and reinstall. This is currently incompatible with PEP 517 and therefore it requires a ``setup.py`` script with the following @@ -202,7 +202,7 @@ Then:: pip install --editable . -This creates a link file in your interpretor site package directory which +This creates a link file in your interpreter site package directory which associate with your source code. For more information, see: (WIP) @@ -216,7 +216,7 @@ basic use here. Transitioning from ``setup.py`` to ``setup.cfg`` ================================================ -To avoid executing arbitary scripts and boilerplate code, we are transitioning +To avoid executing arbitrary scripts and boilerplate code, we are transitioning into a full-fledged ``setup.cfg`` to declare your package information instead of running ``setup()``. This inevitably brings challenges due to a different syntax. Here we provide a quick guide to understanding how ``setup.cfg`` is -- cgit v1.2.1 From 95cacfa6c55fc1c8944b7e9b4086c09088ea4b88 Mon Sep 17 00:00:00 2001 From: Mozi <29089388+pzhlkj6612@users.noreply.github.com> Date: Sun, 12 Sep 2021 15:03:16 +0800 Subject: docs(quickstart): add link to "Development Mode" --- docs/userguide/quickstart.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 1bd04ded..bcb282ed 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -201,7 +201,7 @@ Then:: pip install --editable . This creates a link file in your interpreter site package directory which -associate with your source code. For more information, see: (WIP) +associate with your source code. For more information, see :doc:`development_mode`. Uploading your package to PyPI -- cgit v1.2.1 From 4f475e9035ff40906024249e81b2f7e5b9bebf14 Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Thu, 11 Nov 2021 15:57:01 +0100 Subject: Document that pip works with editable setup.cfg --- docs/userguide/quickstart.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index bcb282ed..9c1d84f9 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -186,17 +186,17 @@ For more details, see :doc:`datafiles` Development mode ================ -``setuptools`` allows you to install a package without copying any files -to your interpreter directory (e.g. the ``site-packages`` directory). This -allows you to modify your source code and have the changes take effect without -you having to rebuild and reinstall. This is currently incompatible with -PEP 517 and therefore it requires a ``setup.py`` script with the following -content:: - import setuptools - setuptools.setup() +.. tip:: + + When there is no ``setup.py`` script present, this is only + compatible with :pep:`517` since :ref:`pip v21.1 `. -Then:: +``setuptools`` allows you to install a package without copying any files +to your interpreter directory (e.g. the ``site-packages`` directory). +This allows you to modify your source code and have the changes take +effect without you having to rebuild and reinstall. +Here's how to do it:: pip install --editable . -- cgit v1.2.1 From ba39e1851f02fa27b425f616d13c2b07298c63d5 Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Fri, 12 Nov 2021 23:56:44 +0100 Subject: Improve the mention of pip version that doesn't need `setup.py` Co-authored-by: Jason R. Coombs --- docs/userguide/quickstart.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/userguide/quickstart.rst') diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index 9c1d84f9..6bf353a0 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -189,8 +189,9 @@ Development mode .. tip:: - When there is no ``setup.py`` script present, this is only - compatible with :pep:`517` since :ref:`pip v21.1 `. + Prior to :ref:`pip v21.1 `, a ``setup.py`` script was + required to be compatible with development mode. With late + versions of pip, any project may be installed in this mode. ``setuptools`` allows you to install a package without copying any files to your interpreter directory (e.g. the ``site-packages`` directory). -- cgit v1.2.1