Documentation for fastai_v1


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! Doku
About the fastai dev category
(Jeremy Howard) #2

Here’s a viewable version of that HTML page from @sgugger:

(Kai Lichtenberg) #3

I created a documentation skeleton for the old version of the library with sphinx (HTML-Build, Code). I found that using nbsphinx makes it pretty nice and easy to embed notebooks into the documentation. I didn’t use it extensively, but it seems pretty flexible. I see no reason why you can not build a completely notebook based documentation with it. There are maybe some advantages: You get the beautiful Read the Docs theme out of the box and you can have an end to end build pipeline from notebooks to deployable static html (notebooks are executed during the build). You can also integrate sites based on Markdown or reStructuredText, which is nice for all kinds of surrounding material like Introduction, Code of Conduct, Abbreviations etc.