Documentation for fastai_v1


#1

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!


Fast.ai Doku
(Jeremy Howard (Admin)) #2

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

https://rawgit.com/fastai/fastai_v1/master/docs/example/notebook_documentation.html


(Kai Lichtenberg) #3

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.


#4

Both links provided by Jeremy and Sylvain seem to be deprecated.
Any new link to the documentation ?


(Michael) #5

See here: http://docs.fast.ai

Best regards
Michael


(Christian Klukas) #6

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


(Jeremy Howard (Admin)) #7

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!)

https://idratherbewriting.com/documentation-theme-jekyll/mydoc_generating_pdfs.html


(Gokkul Nath T S) #8

There seems to be bug in vision Page: When i try to navigate to


(Jeremy Howard (Admin)) #9

Many thanks - will fix.


(Christian Klukas) #10

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…


(German Goldszmidt) #11

@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?


(Michael) #12

I use the „site:“ feature from google:
https://www.google.com/search?q=site:docs.fast.ai+Your%20search


(German Goldszmidt) #13

@MicPie I tried it, eg “site:docs.fast.ai Your search channel” and always returns with a single page,
" Page Not Found

Sorry, but the page you were trying to view does not exist. Try searching for it or looking at the URL to see if it looks correct."


(Wayne Nixalo) #14

I’m doing a clean install of fastai 1.0.X. If you do a dev install in an environment the CLI test will fail:

jupyter nbconvert --execute --ExecutePreprocessor.timeout=600 --to notebook examples/tabular.ipynb

because the kernel used will point to your Python 3 path. You can specify the kernel to use, so if you previously ran:

python -m ipykernel install --user --name fastai --display-name "Python 3 (fastai)"

(where your environment is ‘fastai’) you can run the CLI test right after installation by telling jupyter which kernel to use:

jupyter nbconvert --execute --ExecutePreprocessor.timeout=600 --to notebook examples/tabular.ipynb --NotebookApp.kernel_name="Python 3 (fastai)"

Of course, you can just open a jupyter notebook and select the kernel normally.


(Rahul Pathak) #15

https://docs.fast.ai/ Link is not working. 404 Error


(Jeremy Howard (Admin)) #16

GitHub Pages is down, so docs will be down until they fix it.