Skip to content

Prefer pyproject README metadata #2052

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Herrtian wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Prefer pyproject README metadata #2052

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 19 additions & 6 deletions source/guides/making-a-pypi-friendly-readme.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,23 +18,32 @@ Formats supported by `PyPI's README renderer <https://github.com/pypa/readme_ren
* Markdown (`GitHub Flavored Markdown <https://github.github.com/gfm/>`_ by default,
or `CommonMark <https://commonmark.org/>`_)

It's customary to save your README file in the root of your project, in the same directory as your :file:`setup.py` file.
It's customary to save your README file in the root of your project, in the
same directory as your :file:`pyproject.toml` file.


Including your README in your package's metadata
------------------------------------------------

To include your README's contents as your package description,
set your project's ``Description`` and ``Description-Content-Type`` metadata,
typically in your project's :file:`setup.py` file.
To include your README's contents as your package description, set the
``readme`` key in your project's :file:`pyproject.toml` file:

.. code-block:: toml

[project]
readme = "README.md"

This sets your project's ``Description`` and ``Description-Content-Type``
metadata.

.. seealso::

* :ref:`writing-pyproject-toml`
* :ref:`description-optional`
* :ref:`description-content-type-optional`

For example, to set these values in a package's :file:`setup.py` file,
use ``setup()``'s ``long_description`` and ``long_description_content_type``.
If your project still configures metadata in :file:`setup.py`, use ``setup()``'s
``long_description`` and ``long_description_content_type``.

Set the value of ``long_description`` to the contents (not the path) of the README file itself.
Set the ``long_description_content_type`` to an accepted ``Content-Type``-style value for your README file's markup,
Expand Down Expand Up @@ -89,6 +98,10 @@ and identifies the markup as GitHub-flavored Markdown:
long_description_content_type='text/markdown'
)

When using this approach, make sure the README file is included in your source
distribution. :ref:`setuptools` includes common README names by default; other
build backends may require explicit configuration.


Validating reStructuredText markup
----------------------------------
Expand Down
Loading