Fixing README.rst to render correctly on PyPI.

[dhermes]

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]

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]

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

[tseaver]

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]

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]

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]

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

[coveralls]

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

[dhermes]

1. 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:

2. 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]

@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]

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

[dhermes]

@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]

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]

LGTM