Python docstrings to GitHub README.md

The other answers are great. But I thought I (the OP) ought to share what I do these days (a year or two after the question).

I use Sphinx and its Markdown extension. Do the following:

Sphinx-markdown-builder

You need sphinx-markdown-builder python module.

 pip install sphinx sphinx-markdown-builder;

Run Sphinx

Not the autodoc, the apidoc!

sphinx-apidoc -o Sphinx-docs . sphinx-apidoc --full -A 'Matteo Ferla'; cd Sphinx-docs;

Configuration

Fix the conf.py file, by following the following or just lazily copy paste the echo command below.

Manual

First uncomment the lines. These are otherwise commented out.

import osimport syssys.path.insert(0, os.path.abspath('../'))

Note the change to ../

One weirdness is that the magic methods get ignored. To override this, add this anywhere:

def skip(app, what, name, obj, would_skip, options):    if name in ( '__init__',):        return False    return would_skipdef setup(app):    app.connect('autodoc-skip-member', skip)

A thing to note: The docstrings ought to be written in restructuredtext (RST). If they are in Markdown, you need to add a mod - see this. The two are similar, but different. For example, a single backquote is required for <code> in Markdown, while two are for RST. If in doubt, several blog posts discuss the merits of RST documentation over Markdown.

Typehinting

RST typehints (:type variable: List) are obsolete as proper typehinting def foo(variable: Optional[List[int]]=None) -> Dict[str,int]: has been introduced since 3.6. To make these work:

 pip install sphinx-autodoc-typehints

And add 'sphinx_autodoc_typehints' at the end of the extensions list. Note the package has hyphens while the module has underscores.

TL;DR

Copy paste this:

echo " import osimport syssys.path.insert(0,os.path.abspath('../'))def skip(app, what, name, obj,would_skip, options):    if name in ( '__init__',):        return False    return would_skipdef setup(app):    app.connect('autodoc-skip-member', skip)extensions.append('sphinx_autodoc_typehints') " >> conf.py;

Showtime

Then it is showtime.

make markdown;

Copy the files and clean however you fancy.

mv _build/markdown/* ../; rm -r Sphinx-docs;

Repeats

It should be noted that when new files are added, the apidoc command needs to be repeated. Nevertheless, I highly recommend generating documentation midway as I realise I am doing something wrong.

I have found some other options for doing this:

https://github.com/coldfix/doc2md

Little convenience tool to extract docstrings from a module or class and convert them to GitHub Flavoured Markdown. Its purpose is to quickly generate README.md files for small projects.

https://github.com/freeman-lab/myopts

This module provides a command line tool for parsing a Python file and generating nice looking markdown with your function definitions. It's extremely opinionated and rigid! But also extremely easy to use.

I have a little bit of code that I use to generate an index file from a project. It's not exactly what you're looking for, but with a little wiggle you could add an if statement for py files (where I only have html and png) and grab the doc = "your DocStrings."...https://gist.github.com/Krewn/6e9acdadddb4bf2a56c0

# WARNING RUNNING THIS FILE WILL OVERIDE EXISTING readme.md FILE IN CWDimport osclass indexer:    path = "~"    username = "" # !!! Enter your github username in the provided quotes.    site = "http://"+username+".github.io"    proj = ""     # !!! Enter your repository name in provided quotes.    prod = []    loc=[]    def __init__(self,p):        self.path=p    def fprep(self,name):        name.replace(".","")        name.replace("\\","/")        return(name)    def refPrep(self):        ref = self.site+"/"+self.proj        for qw in self.loc:            ref+="/"+qw        return(ref)    def HtmlFrek(self,adir):        self.loc.append(adir)        os.chdir(adir)        pys = [f for f in os.listdir('.') if os.path.isfile(f) and f.split(".")[len(f.split("."))-1]=="py"]        for i in pys:            Open the file i get the __doc__ string and append it to ret        for k in folders:            if(k.__contains__(".")):                continue            ret+=self.HtmlFrek(k)        os.chdir("..")        del self.loc[len(self.loc)-1]        return(ret)    def HtmlProd(self):        ret = ""        pys = [f for f in os.listdir('.') if os.path.isfile(f) and f.split(".")[len(f.split("."))-1]=="py"]        for i in pys:            Open the file i get the __doc__ string and append it to ret        folders = [f for f in os.listdir(".") if not os.path.isfile(f)]        for k in folders:            if(k.__contains__(".")):                continue            ret+=self.HtmlFrek(k)        self.prod = ret        return(ret)i = indexer(".")q=i.HtmlProd()#print i.prodw = open("readme.md","w")w.write(q)w.close()