Search code examples
pythongithubpypirestructuredtextread-the-docs

How can I compose the content of my PyPI project description?

I am developping a Python project with the following layout (setup with PyScaffold):

project/
 - src/
 - docs/
   - _static/
     - assets/
       - logo.svg
   - index.rst
 - README.rst
 - AUTHORS.txt
 - setup.py
 - setup.cfg
 - ...

This project is hosted on GitHub, published on Pypi, and documented on ReadTheDocs. I would like that these 3 sites render a similar content as main page (README, long description, index page) except for some details:

  • On GitHub, links should redirect to GitHub file page
  • On Pypi and Read the Docs, links should redirect to Read the Docs pages
  • On branches on GitHub, links should redirect to branched files (not master ones)

Currently, I use a README.rst looking like:

.. _Authors: http://readthedocs/latest/authors.html

.. |logo| image:: http://readthedocs/assets/logo.svg
   :alt: Logo
   :width: 500


.. EndOfLinks

|logo|

`Authors`_

A docs/index.rst as follow:

.. _Authors: ./authors.html

.. |logo| image:: ./_static/ewmh_m2m.svg
   :alt: Logo
   :width: 500

.. include:: ../README.rst
   :start-after: EndOfLinks

And a setup.cfg:

long-description = file: README.rst
long-description-content-type = text/x-rst; charset=UTF-8

However, on new branches, the README rendering or links do not reflect any changes in the underlying files, like in this example.

Using relative links in the README makes broken links in the Pypi description as well as logo not displayed (see here)

I tried with a dedicated pypi_description.rst file, similar to index.rst Pypi and GitHub do not render the RST if it contains include directive too.

Solution

  • If the first attempt you describe is sufficient for GitHub and RTD, then the question is just how to achieve a valid long description source for PyPI, right?

    In setup.py, you can set the setup() key word argument long_description_content_type='text/x-rst' and set long_description to a string of RST text (no sphinx extensions), so you can preprocess the long description source with arbitrary Python code earlier in the setup.py.