As Jeremy mentioned earlier, fastai_v1 will be documented in notebooks because it’s flexible, can easily show examples of how things work, and ultimately, there will be link between the doc and the notebook that created it in a sandbox somewhere to let the user play with it and interact with the function he’s reading the doc of.
Since there is no library that exists now to do this automatically, we decided to create our own version of it and you can see the first results here.
The trick is that everything is done by python commands that are executed inside the notebook. By re-executing the notebooks periodically, we can be sure that the doc is in sync with the current code (in terms of new functions, classes, arguments). For instance the table of content of the helper page of a given module is generated by get_mod_toc(mod_name), and the doc of a given function by show_doc_from_name(mod_name,ft_name). The latter parses the arguments, their type given by an annotation and the defaults, to show them as the function is executed (not unlike a ?? in jupyter notebook).
To make things nice, we work with an extension called hide input which (guess what…) hides the input of a cell. That way, in the final notebook, we can only see the clean outputs and not the messy inputs (though we can choose to show some inputs, for instance when giving an example of use). Then we use nbconvert to convert the notebook into an html page.
For now, I’ve focused on generating automatically skeleton notebooks from the modules, and creating a few helper functions to make life easy for the end user. There is also an update script that will insert new functions if they are added in the code. It’s probably a bit bugged since this is a first attempt, but you should be able to get the idea before we release the first fastai_v1 modules. Then we’ll need some help to properly document them!
It’s also ugly, so if someone is good with css and wants to make us a nice style for this, don’t be shy!