Doc updates for pyproject.toml and instructions for pypi (#480)

* Adding docs for pyproject.toml, and some additional instructions for trusted publishing via pypi.

* Update docs/practices/customizing_project.rst

Co-authored-by: Melissa DeLucchi <[email protected]>

* Apply suggestions from code review

* Update docs/practices/customizing_project.rst

---------

Co-authored-by: Melissa DeLucchi <[email protected]>

docs/index.rst

@@ -51,4 +51,5 @@ please :doc:`/source/contact`
    practices/issue_pr_templating
    practices/sphinx
    practices/publishing_package
+   practices/customizing_project
 

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.<blah>]``. 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 <https://packaging.python.org/en/latest/guides/writing-pyproject-toml/>`_.

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