November 1, 2016

Markdown for PyPI: A Solution for Restructured Text | Bonsai

Markdown for PyPI: A Solution for Restructured Text | Bonsai

Markdown for PyPI

The Problem: The Team wants to use Markdown, but PyPI supports reStructured Text

Recently, we rolled out our CLI, library, and configuration code to the Python Package Index, PyPI. One of the first things we noticed was that our perfectly sensible Github-flavored Markdown file had been transformed into a barely-legible mess: 

The file is a python program, and we were leveraging this to pull the file and drop it in the long_description field when building our distribution files. A bit of research found that the correct format for PyPI is actually reStructured Text. I couldn't reasonably re-write all of our READMEs and ask the whole team to change to a new format; something else must be done.

The Solution: Pandoc to the rescue!

Trawling the net, I found a solution in Pandoc, a universal markup translator. This has the magical property of being able to translate a Markdown formatted file into reST format, and more importantly was available in pip as a universal Python library. I figured the best solution would be to import this module into the file. To follow the existing pattern, I made a function around the convert statement, but I chose to name the function rather than using an un-named lambda function, per our PEP style guide.

Bonus Round: Test to make sure we have Pandoc installed

We always want to code for maintainability, and since I can't predict the conditions under which this open source package would be built, it is appropriate for me to make arrangements for future users to have a safe experience. To ensure this, I handled exceptions from failure to import pypandoc by substituting a function with the same name, but the previous load-only behavior.

The Result: An easy to write AND easy to read README!

Once I had my diff (similar to a Pull Request) approved in our Phabricator and the next release came out, I was able to verify my work. Our team is still able to use familiar Markdown syntax to amend the README, and our output is compliant with the expectations of PyPI and looks great!

Subscribe to our newsletter to stay up-to-date on our latest product news & more!