Maroun Maroun Maroun Maroun - 5 months ago 14
Python Question

PyPi description markdown doesn't work

I uploaded a package to PyPi using:

python setup.py register -r pypi
python setup.py sdist upload -r pypi


I'm trying to modify the decsription, I wrote (please don't edit the formatting of the following piece of code, I made it in purpose to demonstrate my problem):

**nose-docstring-plugin**

This plugin enables you to modify docstring of tests based on their attributes, for example:
```python
@attr(section='MySection', type='functional+', module='MyModule', id=1)
def test_function(self):
"""
This is the original docstring
"""
pass
```


However, the text appears as it is, without the markdown formatting. What am I doing wrong?

Answer

PyPI does not support Markdown, so your README will not be rendered into HTML.

If you want a rendered README, stick with reStructuredText; the Sphinx introduction to reStructuredText is a good starting point.

You probably want to install the docutils package so you can test your document locally; you want to run the included rst2html.py script on your README to see what errors are produced, if any. Your specific sample has too many errors:

$ bin/rst2html.py test.rst  > /tmp/test.html
test.rst:7: (ERROR/3) Unexpected indentation.
test.rst:3: (WARNING/2) Inline literal start-string without end-string.
test.rst:3: (WARNING/2) Inline interpreted text or phrase reference start-string without end-string.
test.rst:11: (WARNING/2) Block quote ends without a blank line; unexpected unindent.
test.rst:11: (WARNING/2) Inline literal start-string without end-string.
test.rst:11: (WARNING/2) Inline interpreted text or phrase reference start-string without end-string.

Your code block is using Github's Markdown extensions, which are entirely wrong for reStructuredText. You could use a reST code block (probably, if the PyPI version of docutils is new enough):

.. code-block:: python

    @attr(section='MySection', type='functional+', module='MyModule', id=1)
    def test_function(self):
        """
        This is the original docstring
        """
        pass

To test this locally you'll need to install Pygments as well.

There is an feature request with pull request to add support for Markdown, if you are interested.

Comments