title: Python docstrings to GitHub README.md
body: <p>How do I transcode Python documentation strings to a GitHub <code>readme.md</code> file?</p>
  <p>Even though it seems like something everyone does, I cannot seem to get a decent solution and I am assuming it should be easy, so it seems unlikely folks are going throw two converters…</p>
  <h3>What I have tried</h3>
  <p><strong>pydoc</strong>  Actually simple. The output of pydoc is manpages (groff format for Unix systems). Which is a dead end as man to md is not a thing. Via HTML, <code>pydoc3 -w</code> + pandoc, utterly munges the docstrings to bits.</p>
  <p><strong>Custom code</strong> There seems to be lots of short custom code, but for the few I tried the output does not seem to be as good as that pydoc, which has a summary, adds inherited methods and lists some attributes.</p>
  <p><strong>mkdocs</strong>. It was suggested somewhere. It just pollutes my folder as it is a misleading name as is a not docstrings &gt; md converter, but a md &gt; html.</p>
  <p><strong>Sphinx + Pandoc.</strong> After fixing an UTF-8 issue, I gave up on Sphinx as I have a single .py script to convert and the autodoc setting of the quickstart did not parse my script. I tried in Python to import <code>sphinx.ext.autodoc</code>, but TBH the documentation was too long and I gave up.</p>
  <h3>NB</h3>
  <p>There is a <a href="https://stackoverflow.com/questions/29660467/automatically-generate-github-wiki-documentation-from-python-docstrings#comment60075289_29660467">year-old unanswered Stack Overflow question</a> on the topic, but I hope that by giving a lot more detail I will get an answer.</p>