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!
Hey!
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.
Hi, I created a bash script which generates a PDF version of the documentation as I plan to read through the current material on my e-reader. Perhaps its also useful for others: https://github.com/cklukas/fastai_docs/tree/master/pdf
Thanks @klukas . It looks like it isn’t rendering correctly - our hidden markup etc is appearing in your output. We’re using Jekyll to generate the HTML - you can also generate PDF from it. Here’s the docs for our theme on how to set it up. If you (or anyone else) gets this working, please submit a PR so we can include it in future builds (with appropriate credit of course!)
My current approach for generating the PDF is more like a quick hack. I tried some things, but didn’t get a better output. Based on tags it should be possible to filter-out some cells, but its quite complex with few experience with that tool chain, and thus time-consuming to find out the right approach…
Online docs are fine for now, and perhaps someone writes a nice extended book one day…
@sgugger “Search” in docs.fast.ai only allows to look for predefined (pre-indexed) text.
Can it be configured to enable search for any text?
Or is there another way to do arbitrary search?