A clever way to release new documentation without releasing a new package that might confuse your user base.

The Problem

After my newest release of yapconf it was brought to my attention that the documentation didn’t look very good on PyPi. You can see for yourself. This made me very sad, as I had worked quite hard on the documentation.

It looked like I was missing some dashes underneath a header. Alas, I did not want to cut a brand new release just to make PyPi look better. After all, it was rendered correctly on GitHub and my readthedocs page also looked pretty good. Still, this irked me, so I took my lamenting to twitter.

Luckily, the Python community is absolutely amazing. I had the pleasure of meeting Brett Cannon, one of the Python core developers (and a key-note speaker at PyCon 2018). Luckily for me Brett had a solution that seemed to solve my problems.

Preventing the Problem

First, there was a library that could have helped me. @btskinn on twitter pointed me to a library called restview which was exactly what I needed. Using it couldn’t be simpler:

Install and run restview 
1
2
 
pip install restview
restview --long-description

This let me see exactly what was wrong with my text. I got something like this in my browser:

<string>:146: (WARNING/2) Title underline too short.

0.3.1 (2018-06-07)

------

If I had used restview from the beginning, I wouldn’t have been in this pickle to begin with. I would have known there was a problem before I released, and fixed it.

Solving the Problem

Sadly, I did not know what the problem was before I released, and I imagine I could miss it again. So I edited my HISTORY.rst and now it looked correct. No more warnings anywhere. I can now use a versioning technique described in PEP-0440 called post relases.

The concept is very simple. You can add .postN to the end of your semantic version for your package. This will indicate to end users that this change has no actual bug fixes and instead are just fixes related to minor errors in, for example, a HISTORY.rst

I just updated my version number 0.3.2 => 0.3.2.post1 and ran make release and boom! The documentation is fixed.

The conclusion

I learned some valuable lessons:

  1. Twitter can be quite helpful.
  2. The Python Community is awesome.
  3. restview is a very helpful library.
  4. The post release version is meant for this problem exactly.

Thanks for reading! If you have a better way to do it, feel free to comment or hit me up on twitter @loganasherjones