1. PyPA
  2. Python Packaging Authority Projects
  3. pypi
  4. Issues


Issue #65 resolved

restructuredText description treated as plain text

Anonymous created an issue

i'm trying out PyPI for the first time, and have a tough luck getting the long_description field (called description in PyPI) render with docutils successfully. the source gets dumped in the package page even with


as the complete content. see https://testpypi.python.org/pypi/hg-request-pull/0.4.99.

Comments (14)

  1. Anonymous
    • changed status to open

    reopening, this happens with obviously correct reST content. check the initial description of this issue.

  2. Anonymous

    Richard Jones how can we check form problems if docutils is absolutely fine with the provided reST? what problems does pypi find in a readme that consists of



  3. Tim Zehta

    I also encountered this error with correct reStructuredText. The error has been intermittent—some times the same rST content/data results in an error, some times it does not.

  4. Richard Jones

    My apologies, I am very short of time at the moment to deal with PyPI issues. The issue is having a document title (initial heading) at the top of the content. That doesn't explain any errors - you just won't see the title heading in the output. This is all a part of the general problem of docutils wanting to be the page that is generated, and we wish to embed the content in a page that already has a title and heading etc.

  5. Jeff Hinrichs

    I concur about the sad state or RST support on pypi. It is a shame that it does not support what sphinx/readthedocs supports. After putting too much time dealing with documenting a package using a RST to support bitbucket, readthedocs now I have to deal with issues in pypi.

    Apologies if I sound curt, but after putting in the time to set up CI, multi-python support, set up modern documentation, getting bit in the backside by this is a bit frustrating. When setting up CI takes substantially less time then dealing with the vagaries of these different RST implementations -- something is very, very wrong.

    Where exactly is this tool to check my RST. I've seen comments about use the command line tool, but since RST isn't my interest a little bit of documentation and a highly visible pre-test tool for what pypi expects and show would be helpful.

  6. Sorin Sbarnea

    Is there any way to check our README.rst files so we can properly use them in pypi. They work perfectly with github and on pypy they are just plain text with no feedback at all.

  7. Anton Backer

    I was seeing this problem as well on https://pypi.python.org/pypi/iphoto/0.2.1 and here's my experience trying to fix it.

    Things that worked:

    • restview --pypi-strict README.rst, mentioned on #161, was the first tool that provided actual feedback (in my case, "link scheme not allowed".)
    • In the absence of restview, there's also the option of randomly tweaking the README and uploading new versions to pypi via python setup.py register until one renders correctly. This is unnecessarily tedious, and I do not recommend it.

    Things that didn't work (but may work for other classes of problems):

    • python setup.py check --restructuredtext --strict output an unhelpful warning, "Could not finish the parsing", which persisted even after I fixed the rst so that pypi was happy with it.
    • rst2html README.rst showed no errors.
  8. Log in to comment