PyPi and use of ReStructuredText

Posted on 17th August 2017

I've in the process of putting together my first proper Python package to be uploaded to PyPi / PyPi Old. The docs around doing this are not great, but the official docs are pretty good:

One thing which was unclear to me was how to specify the text which gets displayed on PyPi. After some playing, it seems that:

  1. This should be set in the long_description variable of setup() or in setup.cfg
  2. This needs to be ReStructuredText not Markdown, for example.

Some searching found a solution:

  • Download Pandoc
  • Download Pypandoc : pip install pypandoc
  • (Or use Conda for both steps in one)

  • Then you can dynamically generate a rst file when setup.py is invoked:

    try:
    import pandoc
    doc = pandoc.Document()
    with open('readme.md', encoding='utf-8') as f:
        doc.markdown = f.read().encode("utf-8")
    with open("README.rst", "wb") as f:
        f.write(doc.rst)
except:
    print("NOT REFRESHING README.rst")

with open('README.rst', encoding='utf-8') as f:
    long_description = f.read()

  • Enclosing in try/except means I haven't broken setup for users without pypandoc

Here's the project on GitHub: TileMapBase

Categories
Recent posts