From 9409cac240b7e3338941d770fa56dd2db817671e Mon Sep 17 00:00:00 2001 From: Drew Oldag <47493171+drewoldag@users.noreply.github.com> Date: Mon, 30 Sep 2024 13:34:42 -0700 Subject: [PATCH] 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 <113376043+delucchi-cmu@users.noreply.github.com> * Apply suggestions from code review * Update docs/practices/customizing_project.rst --------- Co-authored-by: Melissa DeLucchi <113376043+delucchi-cmu@users.noreply.github.com> --- docs/index.rst | 1 + docs/practices/customizing_project.rst | 23 +++++++++++++++++++++++ docs/practices/pypi.rst | 7 +++++-- 3 files changed, 29 insertions(+), 2 deletions(-) create mode 100644 docs/practices/customizing_project.rst 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