summaryrefslogtreecommitdiff
path: root/docs/userguide/quickstart.rst
diff options
context:
space:
mode:
authorAnderson Bravalheri <andersonbravalheri@gmail.com>2022-06-16 21:59:01 +0100
committerAnderson Bravalheri <andersonbravalheri@gmail.com>2022-06-16 21:59:01 +0100
commit9d487039eaab63eda2283c69653ef1b09ccf702d (patch)
treec4ac1007e69496f3dc898753b42070097511002c /docs/userguide/quickstart.rst
parent9c7163bc6030e546ba1133de823d0b4ac06a02d9 (diff)
downloadpython-setuptools-git-9d487039eaab63eda2283c69653ef1b09ccf702d.tar.gz
docs: Reorder example tabs
Diffstat (limited to 'docs/userguide/quickstart.rst')
-rw-r--r--docs/userguide/quickstart.rst117
1 files changed, 59 insertions, 58 deletions
diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst
index 4e3d7328..5ee1ce7b 100644
--- a/docs/userguide/quickstart.rst
+++ b/docs/userguide/quickstart.rst
@@ -66,6 +66,20 @@ The following example demonstrates a minimum configuration
(which assumes the project depends on :pypi:`requests` and
:pypi:`importlib-metadata` to be able to run):
+.. tab:: pyproject.toml
+
+ .. code-block:: toml
+
+ [project]
+ name = "mypackage"
+ version = "0.0.1"
+ dependencies = [
+ "requests",
+ 'importlib-metadata; python_version<"3.8"',
+ ]
+
+ See :doc:`/userguide/pyproject_config` for more information.
+
.. tab:: setup.cfg
.. code-block:: ini
@@ -98,20 +112,6 @@ The following example demonstrates a minimum configuration
See :doc:`/references/keywords` for more information.
-.. tab:: pyproject.toml
-
- .. code-block:: toml
-
- [project]
- name = "mypackage"
- version = "0.0.1"
- dependencies = [
- "requests",
- 'importlib-metadata; python_version<"3.8"',
- ]
-
- See :doc:`/userguide/pyproject_config` for more information.
-
Finally, you will need to organize your Python code to make it ready for
distributing into something that looks like the following
(optional files marked with ``#``)::
@@ -166,6 +166,21 @@ Therefore, ``setuptools`` provides a convenient way to customize
which packages should be distributed and in which directory they should be
found, as shown in the example below:
+.. tab:: pyproject.toml (**BETA**) [#beta]_
+
+ .. code-block:: toml
+
+ # ...
+ [tool.setuptools.packages]
+ find = {} # Scan the project directory with the default parameters
+
+ # OR
+ [tool.setuptools.packages.find]
+ where = ["src"] # ["."] by default
+ include = ["mypackage*"] # ["*"] by default
+ exclude = ["mypackage.tests*"] # empty by default
+ namespaces = false # true by default
+
.. tab:: setup.cfg
.. code-block:: ini
@@ -196,21 +211,6 @@ found, as shown in the example below:
# ...
)
-.. tab:: pyproject.toml (**BETA**) [#beta]_
-
- .. code-block:: toml
-
- # ...
- [tool.setuptools.packages]
- find = {} # Scan the project directory with the default parameters
-
- # OR
- [tool.setuptools.packages.find]
- where = ["src"] # ["."] by default
- include = ["mypackage*"] # ["*"] by default
- exclude = ["mypackage.tests*"] # empty by default
- namespaces = false # true by default
-
When you pass the above information, alongside other necessary information,
``setuptools`` walks through the directory specified in ``where`` (omitted
here as the package resides in the current directory) and filters the packages
@@ -239,6 +239,14 @@ to type ``python -m pip install``.
The following configuration examples show how to accomplish this:
+
+.. tab:: pyproject.toml
+
+ .. code-block:: toml
+
+ [project.scripts]
+ cli-name = "mypkg.mymodule:some_func"
+
.. tab:: setup.cfg
.. code-block:: ini
@@ -260,13 +268,6 @@ The following configuration examples show how to accomplish this:
}
)
-.. tab:: pyproject.toml
-
- .. code-block:: toml
-
- [project.scripts]
- cli-name = "mypkg.mymodule:some_func"
-
When this project is installed, a ``cli-name`` executable will be created.
``cli-name`` will invoke the function ``some_func`` in the
``mypkg/mymodule.py`` file when called by the user.
@@ -281,6 +282,18 @@ Packages built with ``setuptools`` can specify dependencies to be automatically
installed when the package itself is installed.
The example below show how to configure this kind of dependencies:
+.. tab:: pyproject.toml
+
+ .. code-block:: toml
+
+ [project]
+ # ...
+ dependencies = [
+ "docutils",
+ "requires <= 0.4",
+ ]
+ # ...
+
.. tab:: setup.cfg
.. code-block:: ini
@@ -300,18 +313,6 @@ The example below show how to configure this kind of dependencies:
# ...
)
-.. tab:: pyproject.toml
-
- .. code-block:: toml
-
- [project]
- # ...
- dependencies = [
- "docutils",
- "requires <= 0.4",
- ]
- # ...
-
Each dependency is represented by a string that can optionally contain version requirements
(e.g. one of the operators <, >, <=, >=, == or !=, followed by a version identifier),
and/or conditional environment markers, e.g. ``sys_platform == "win32"``
@@ -332,6 +333,16 @@ Including Data Files
Setuptools offers three ways to specify data files to be included in your packages.
For the simplest use, you can simply use the ``include_package_data`` keyword:
+.. tab:: pyproject.toml (**BETA**) [#beta]_
+
+ .. code-block:: toml
+
+ [tool.setuptools]
+ include-package-data = true
+ # This is already the default behaviour if your are using
+ # pyproject.toml to configure your build.
+ # You can deactivate that with `include-package-data = false`
+
.. tab:: setup.cfg
.. code-block:: ini
@@ -349,16 +360,6 @@ For the simplest use, you can simply use the ``include_package_data`` keyword:
# ...
)
-.. tab:: pyproject.toml (**BETA**) [#beta]_
-
- .. code-block:: toml
-
- [tool.setuptools]
- include-package-data = true
- # This is already the default behaviour if your are using
- # pyproject.toml to configure your build.
- # You can deactivate that with `include-package-data = false`
-
This tells setuptools to install any data files it finds in your packages.
The data files must be specified via the |MANIFEST.in|_ file
or automatically added by a :ref:`Revision Control System plugin