12

There are two version of my little tool:

In the last update a change in README.rst cases a warning:

user@host> rst2html.py README.rst  > /tmp/foo.html
README.rst:18: (WARNING/2) Inline emphasis start-string without end-string.
README.rst:18: (WARNING/2) Inline emphasis start-string without end-string.

Now the pypi page looks ugly :-(

I use this recipe to do CI, bumpversion, upload to pypi: https://github.com/guettli/github-travis-bumpversion-pypi

How could I ensure that no broken README.rst gets released any more? With other words I want to avoid that the pypi page looks ugly.

Dear detail lovers: Please don't look into the current particular error in the README.rst. That's is not the question :-)

guettli
  • 25,042
  • 81
  • 346
  • 663

3 Answers3

18

Update

As of Sep 21, 2018, the Python Packaging Authority recommends an alternative command twine check. To install twine:

pip install twine
twine check dist/*

Note that twine requires readme_renderer. You could still use readme_renderer, and you only need to install twine if you want its other features, which is a good idea anyway if you are releasing to PyPI.

From the official Python packaging docs, Uploading your Project to PyPI:

Tip: The reStructuredText parser used on PyPI is not Sphinx! Furthermore, to ensure safety of all users, certain kinds of URLs and directives are forbidden or stripped out (e.g., the .. raw:: directive). Before trying to upload your distribution, you should check to see if your brief / long descriptions provided in setup.py are valid. You can do this by following the instructions for the pypa/readme_renderer tool.

And from that tool's README.rst:

To check your long description's locally simply install the readme_renderer library using:

$ pip install readme_renderer
$ python setup.py check -r -s
adrin
  • 4,511
  • 3
  • 34
  • 50
Steve Piercy
  • 13,693
  • 1
  • 44
  • 57
  • Great. Yes you are right. The readme_renderer has the authoritative answer if the REAME is valid or not. Thank you! – guettli Oct 12 '17 at 07:43
  • Now I have the tool to do this. My next step is how to call it. Up to now I see two ways: use subprocess or use it like a library. Maybe there is a third way. I am unsure what is better. – guettli Oct 16 '17 at 08:46
  • @guettli are you asking a separate question? If so please create one. Otherwise please accept this answer if it did in fact solve your problem. – Steve Piercy Oct 19 '17 at 01:18
  • This command says it was deprecated in favor of `twine check`, but doesn't give a full set of instructions on where to how to install this. – AlanSE Jul 19 '19 at 19:22
  • @AlanSE where do you see deprecation of `readme_renderer`? `twine check` uses it. – Steve Piercy Jul 20 '19 at 08:38
  • For historical documentation, running the pip install & setup.py as check gave me "warning: Check: This command has been deprecated. Use `twine check` instead". It looks like you have already updated your answer. Exact use of that would vary by project, but `python setup.py install` and then `twine check dist/*` works for the particular one I was testing, and is a not-deprecated way of doing this now. – AlanSE Jul 22 '19 at 12:56
4

Preamble

I had a readme which would not render on PyPi, other than the first element on the page (an image). I ran the file against multiple validators, and tested it against other renders. It worked perfectly fine everywhere else! So, after a long, nasty fight with it, and numerous version bumps so I could test a PyPi revision, I tried reducing the file to a bare minimum, from which I'd build it back up. It turned out that the first line was always processed, and then nothing else was...

Solution

Discovering this clue regarding the first line, I then had an epiphany... All I had to do was change the line endings in the file! I was editing the file in Windows, with Windows line endings being tacked on implicitly. I changed that to Unix style and (poof!) PyPi fully rendered the doc!

Rant...

I've encountered such things in the past, but I took it for granted that PyPi would handle cross platform issues like this. I mean one of the key features of Python is being cross platform! Am I the first person working in Windows to encounter this?! I don't appreciate the hours of time this wasted.

BuvinJ
  • 10,221
  • 5
  • 83
  • 96
2

You could try if rstcheck catches the type of error in your readme. If it does, run it after pytest in your script section. (and add it in your requirements ofc).

renefritze
  • 2,167
  • 14
  • 25