Fixing README.rst to render correctly on PyPI. #434

dhermes · 2014-12-18T06:15:00Z

Main changes:

Using named links instead of anonymous
Using an absolute instead of project relative link for
CONTRIBUTING
Changing duplicated link text so that they differ
Lining up :target: with the line above for embedded img's

H/T to
https://github.com/coagulant/coveralls-python/blob/master/README.rst
for guidance.

dhermes · 2014-12-18T06:15:43Z

I'm not 100% this will work so a PyPI maintainer should upload the new RST via:
https://pypi.python.org/pypi?%3Aaction=pkg_edit&name=gcloud
to make sure.

coveralls · 2014-12-18T06:17:34Z

Coverage remained the same when pulling 76ce9e6 on dhermes:fix-readme-for-pypi into c2ba130 on GoogleCloudPlatform:master.

tseaver · 2014-12-18T16:02:15Z

Here is how I test the renderings:

$ python setup.py --long-description | rst2html > /tmp/foo && firefox /tmp/foo

Warnings show up in nice, hard-to-ignore dropshadow boxes.

tseaver · 2014-12-18T16:19:03Z

My example assumed that we were setting the long_description argument to setup() based on README.rst, which we don't (but should). E.g.:

import os

from setuptools import setup, find_packages

here = os.path.abspath(os.path.dirname(__file__))
with open(os.path.join(here, 'README.rst')) as f:
    README = f.read()

setup(
    name='gcloud',
    version='0.3.0',
    description='API Client library for Google Cloud',
    long_description=README,
    #...
)

It could include CHANGES.rst, too, if we hand that file. E.g.:

import os

from setuptools import setup, find_packages

here = os.path.abspath(os.path.dirname(__file__))
with open(os.path.join(here, 'README.rst')) as f:
    README = f.read()
with open(os.path.join(here, 'CHANGES.rst')) as f:
    CHANGES = f.read()

setup(
    name='gcloud',
    version='0.3.0',
    description='API Client library for Google Cloud',
    long_description='\n\n'.join([README, CHANGES]),
    #...
)

Doing it that way avoids the need to upload a file: it gets done during the setup.py register stage automatically.

tseaver · 2014-12-18T16:20:00Z

BTW, the following::

$ rst2html < README.rst > foo.html

shows that the error preventing rendring on PyPI is the inclusion of the .. code:: role, which is Sphinx-only.

dhermes · 2014-12-18T17:50:19Z

Great! Thanks for that. I googled around for RST validators and had no luck. Will fix the Sphinx parts and ping again.

Main changes: - Using named links instead of anonymous - Using an absolute instead of project relative link for CONTRIBUTING - Changing duplicated link text so that they differ - Lining up :target: with the line above for embedded img's H/T to https://github.com/coagulant/coveralls-python/blob/master/README.rst for guidance.

coveralls · 2014-12-18T17:58:02Z

Coverage remained the same when pulling 48249e1 on dhermes:fix-readme-for-pypi into 1f2ed88 on GoogleCloudPlatform:master.

dhermes · 2014-12-18T18:07:29Z

Leaving the .. code section in renders just fine (and with syntax highlighting):

as compared to using just the Some text:: directive (like coagulant does), which doesn't look great:

A StackOverflow post indicates that :code: may be an issue but one of the comments notes that .. code is included in the PyPI code.

I think the more likely culprit was the relative link to CONTRIBUTING.rst.

dhermes · 2014-12-18T18:32:02Z

@tseaver I finally got access to the PyPI project and played around (a bit of binary search) until it rendered.

It turns out the remaining issue was the final relative link LICENSE <LICENSE>__. #Fail that I missed it.

You can check out https://pypi.python.org/pypi/gcloud now and it renders perfectly.

coveralls · 2014-12-18T18:32:39Z

Coverage remained the same when pulling beb58b1 on dhermes:fix-readme-for-pypi into 1f2ed88 on GoogleCloudPlatform:master.

dhermes · 2014-12-18T18:55:18Z

@tseaver PTAL

Is it safe to set

--- a/setup.py
+++ b/setup.py
@@ -25,6 +25,7 @@ setup(
     name='gcloud',
     version='0.3.0',
     description='API Client library for Google Cloud',
+    long_description=open('README.rst', 'r').read(),
     author='JJ Geewax',
     author_email='[email protected]',
     scripts=[],

Also, in doing this, python setup.py --long-description | rst2html didn't give me any warnings about the relative links (LICENSE and CONTRIBUTING).

tseaver · 2014-12-18T19:44:58Z

Should be fine to update setup.py to include the long_description. Maybe do it via a with statement to avoid resource warnings under Py3k?

tseaver · 2014-12-18T19:45:04Z

LGTM

Fixing README.rst to render correctly on PyPI.

Source-Link: googleapis/synthtool@703554a Post-Processor: gcr.io/cloud-devrel-public-resources/owlbot-python:latest@sha256:94961fdc5c9ca6d13530a6a414a49d2f607203168215d074cdb0a1df9ec31c0b