diff --git a/docs/index.rst b/docs/index.rst index e11553e..caaf260 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -51,4 +51,5 @@ please :doc:`/source/contact` practices/issue_pr_templating practices/sphinx practices/publishing_package + practices/customizing_project diff --git a/docs/practices/customizing_project.rst b/docs/practices/customizing_project.rst new file mode 100644 index 0000000..51b2c70 --- /dev/null +++ b/docs/practices/customizing_project.rst @@ -0,0 +1,23 @@ +Configuration with pyproject.toml +=============================================================================== + +What is it? Why do it? +------------------------------------------------------------------------------- + +The ``pyproject.toml`` file is used to define many different project configurations. +It replaces the need for setup.py, requirements.txt, and other configuration files. + +A fundamental use for ``pyproject.toml`` is to define dependencies. You should +make an effort to add all the required dependencies to the ``[dependencies]`` +section of the file. The template also creates a section for dependencies used only in development: ``[project.optional-dependencies][dev]``. You can add additional sets of optional dependencies here, e.g. for extended feature sets. + +In addition to dependencies, ``pyproject.toml`` centralizes the project's +configuration and makes it easier to manage. If you examine your ``pyproject.toml`` +file, you'll see sections with titles like ``[tool.]``. These sections are +used to configure tools that are used in the project that would otherwise require +their own configuration files. + +A ``pyproject.toml`` file provides a vast number of customization options well +beyond what can be covered here. For an in-depth look at how the file can be used +and how it compares to the older ``setup.py`` checkout the +`Python Packaging User Guide `_. diff --git a/docs/practices/pypi.rst b/docs/practices/pypi.rst index 988fd42..5c2dced 100644 --- a/docs/practices/pypi.rst +++ b/docs/practices/pypi.rst @@ -26,8 +26,11 @@ To support this, you'll need to configure your repository. * For previously unpublished packages: https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/ * For existing published packaged: https://docs.pypi.org/trusted-publishers/adding-a-publisher/ - -* When configuring your trusted publisher, the value to use for the "Workflow name" is "publish-to-pypi.yml". + +* When configuring your trusted publisher + + * Set the value of "Workflow name" to "publish-to-pypi.yml". + * Leave the value of "Environment name" blank. Releasing new versions