Documentation improvements


(Nick Switanek) #26

When I try to open vision.image.ipynb I get a “Notebook failed to load” error:

The error was:

[sprintf] expecting number but found string

See the error console for details.

I don’t see any details logged in the error console.


(Nick Switanek) #27

I’m sorry if I’ve missed this somewhere, but:
What is the relationship between the notebooks and the html, for example, between vision.image.ipynb and vision.image.html?

Not sure if related, but there is this sentence in gen_doc_main.html:
“If you want to help us and contribute to the docs, you just have to make modifications to the source notebooks, our scripts will then automatically convert them to HTML.”
But I don’t see a clear relationship between .html and .ipynb files sharing the same file name.


(Pierre Ouannes) #28

I had a similar issue and Stas helped me out. You can see my posts here.
To sum it up :

  • Make sure you ran pip install -e ".[dev]" as per here
  • If it’s still not working, make sure your conda env is activated by following this section instructions

(Pierre Ouannes) #29

Is something like this gist what you are looking for ? I choosed to use the fastai function rather than the callback when possible.

Any feedback would be appreciated :slight_smile:


#30

Yes! If you add trainings, maybe make them short (2-3 epochs) so that the notebook doesn’t take too long to run. For 1cycle, you should show the momentums with the LRs since they change as well.


(Pierre Ouannes) #31

All right thanks !

To illustrate the General Scheduler could you point me to a kind of schedule I could implement ? Otherwise I’ll just redo SGD with warm restarts that’s already on the specific page for the General Scheduler but isn’t it a bit repetitive ?


#32

Just do something in two epochs with two different variations. No need to be really useful.


(Pierre Ouannes) #33

Here’s what I did for the first few callbacks. I’ll do a PR if it’s all right with you.

I changed the order of the callbacks to try to be coherent. It would be best if the order in the overview matched the order in the menu “callbacks”, but I don’t know how to change that menu. Any pointers ?


#34

Seems good. Just one note on mixup: I wouldn’t show an example of fit since it doesn’t explain what mixup does. Here giving a general explanation is probably enough.
Thanks for the work!


(Pierre Ouannes) #35

My PR from yesterday about visible show_doc() doesn’t seem so have an effect on how it looks on the website. That’s weird because for example let’s take this instance (just above the linked section). When I find the corresponding cell in the fastai source it indeed says hide_input = true but that’s not reflected on the doc page, even though it was last generated today.

Here’s the full cell of the example that show hide_input = true:

{
“cell_type”: “code”,
“execution_count”: null,
“metadata”: {
“hide_input”: true
},
“outputs”: [
{
“data”: {
“text/markdown”: [
“<h2 id=“OneCycleScheduler”>class OneCycleScheduler<a href=“https://github.com/fastai/fastai/blob/master/fastai/callbacks/one_cycle.py#L9” class=“source_link”>[source]\n”,
“\n”,
“> OneCycleScheduler(learn:Learner, lr_max:float,moms:Floats=(0.95, 0.85), div_factor:float=25.0, pct_start:float=0.3) :: [Callback(/callback.html#Callback)\n”,
“\n”,
"Manage 1-Cycle style training as outlined in Leslie Smith’s paper. "
],
“text/plain”: [
“<IPython.core.display.Markdown object>”
]
},
“metadata”: {},
“output_type”: “display_data”
}
],
“source”: [
“show_doc(OneCycleScheduler)”
]
}


#36

That’s because I didn’t regenerate the website. I was going to to it yesterday and then forgot. Will run the script sometime today.


(Pierre Ouannes) #37

Oh okay. So what does “Site last generated: Dec 20, 2018” on the bottom right mean ?


#38

I think it’s in link with the last commit, or @stas is it something the building tool adds?


(Stas Bekman) #39

It means that is when github rebuilt the site. It’s done automatically. It’s unrelated to when the html docs were generated.

As @sgugger said your commit to docs_src, @PierreO, wasn’t converted to html yet, so it’s not live yet.

The flow is: docs_src (.ipynb) -> docs (md/html)-> githubpages website.


(Pierre Ouannes) #40

I see ! Thanks for the explanation :slight_smile:


(Stas Bekman) #41

For better documentation, I think it’d also be a good idea to migrate some of the notes in forums to corresponding fastai docs, often it’s very difficult to find some of those gems in the forums.

So if you stumble upon useful summaries, tips, performance notes, and other useful information that can be extracted/compiled into a stand-alone document or a section of an existing one, that would be a great service to this community.

In general we put normal user docs under fastai’s repo docs/*md, and more of the core dev docs under docs/dev/*md, but don’t worry too much about the proposed placement - it’s easy to reorganize those later.

Reading through some of the posts by @jeremy and @sgugger is probably a good starting point, but there are plenty other wonderful contributions by others hidden in the forums.


Improving/Expanding Functional Tests
How to contribute to fastai [Discussion]
(Stas Bekman) #42

I compiled some of the answers in this thread into extra notes in the first post. The first post is now a wiki, so please don’t hesitate to improve it.

But also, ideally, improve the main document on doc authoring: https://docs.fast.ai/gen_doc_main.html.

Thank you.


(Stas Bekman) #43

I created a new step-by-step section on “Process for contributing to the docs”: https://docs.fast.ai/gen_doc_main.html#process-for-contributing-to-the-docs

please let me know if you find any problems/difficulties with it.


(Stas Bekman) #44

Here is another project, but this one is on the system-level wrt function definitions:

fastai uses an elaborate system of arg types encoded in the functions and shown via show_doc.

How does one find out what those types are? e.g.: https://docs.fast.ai/data_block.html#LabelLists.add_test

add_test[source] 
add_test(items:Iterator[T_co], label:Any=None)

What is T_co? (please don’t answer this question literally) Perhaps the docs need to include a page with the different types and have those types crosslinked to that page?

and why is there a need for an extra note?

“Note: Here items can be an ItemList or a collection.?”

I thought the purpose of the complex typestrings was to take care of not needing to explain what each argument is? And to a user this note is not very clear. ItemList is clear, a collection is not - a collection of what?

The point I’m trying to convey is that a lot of those things are very clear to the person who designed the system, but to a user they appear overly cryptic and confusing, IMHO.


(Stas Bekman) #45

The doc website needs a cleanup - it contains files that shouldn’t be there.

There is https://docs.fast.ai/tta.html, which I think shouldn’t be there, as there is no tta.ipynb. There are seem to be 4 of them:

perl -le 'for (@ARGV) { $x=$_; s#docs/(.*?)\.html#docs_src/$1.ipynb#; print "$x" unless -e $_} ' docs/*html
docs/callbacks.tracking.html
docs/text.models.qrnn.html
docs/tooltips.html
docs/tta.html

@sgugger, is it OK to nuke those 4?