diff options
| author | Anderson Bravalheri <andersonbravalheri@gmail.com> | 2022-06-16 21:59:01 +0100 |
|---|---|---|
| committer | Anderson Bravalheri <andersonbravalheri@gmail.com> | 2022-06-16 21:59:01 +0100 |
| commit | 9d487039eaab63eda2283c69653ef1b09ccf702d (patch) | |
| tree | c4ac1007e69496f3dc898753b42070097511002c /docs/userguide/quickstart.rst | |
| parent | 9c7163bc6030e546ba1133de823d0b4ac06a02d9 (diff) | |
| download | python-setuptools-git-9d487039eaab63eda2283c69653ef1b09ccf702d.tar.gz | |
docs: Reorder example tabs
Diffstat (limited to 'docs/userguide/quickstart.rst')
| -rw-r--r-- | docs/userguide/quickstart.rst | 117 |
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 |
