We have a Python project where our documentation is currently spread across three places: we have example Python files, we have Sphinx docs (some of which are generated from IPython notebooks) and we have IPython notebooks. We are considering consolidating all this documentation into one set of IPython notebooks. Ultimately we want to make life easier for both our users and developers by moving all our docs to one place, and using one tool (IPython notebook). And, to be honest, minimising the time required to maintain the docs is a high priority here: all the developers are working for free, in their spare time.
One big advantage of Sphinx over IPython notebooks is that Sphinx can automatically generate API documentation from the code using apidoc. My hunch is that it should be possible to replicate this behaviour in an IPython notebook by writing some code which walks over the library's python files, extracts the docstrings for display in a notebook (including rendering any maths or images and the relevant sections of the docstring (parameters, return value, notes etc)). My question is: does such a tool already exist? i.e. a tool which can walk over a Python directory, extract the docstrings and display them in an IPython notebook, ideally using pretty HTML formatting?
Here are two links that you might find useful:
https://github.com/rossant/ipymd: this lets you use the IPython notebook frontend on Markdown documents. There is also a md<->ipynb conversion CLI tool. It can be easier to deal with Markdown documents than ipynb files in a doc-generation tool.
https://github.com/kwikteam/phy/blob/master/tools/api.py: a quick script that I wrote to generate an API documentation in Markdown from a Python project. There is no notebook involved here, but you can use ipymd to convert it to a notebook, or to edit it in the notebook frontend.