Documentation improvements


#86

I tried to fix the links. But unfortunately I just could fix a few. This is probably not enough for a pull request. :sweat_smile: I haven’t found out yet how the method show_doc() creates text, which is included into the docs then. And for some links I couldn’t find the class descriptions in the docs to which they refer. I’m not sure if the docs are not up to date, but I assume I simply just don’t know too much about the fastai library, yet. :sweat_smile: I just watched the second lesson of the course.

Oh, one more thing, that I noticed. When I tried to run the script for testing the docs locally, I got an error, which said, that a folder could not be find. Then I changed the path inside the script, which made the script run. However, the result was different compared to the results generated by the non-local test script. Thus, I wondered if the script is broken!? But I assume, I made something wrong (although I think I followed the instructions)!?


How to contribute to fastai [Discussion]
(Stas Bekman) #87

Thank you for wanting to contribute to the fastai docs, @bam098.

Any small fix counts - so even a single url fixed is a goodness.

docs.fast.ai is pretty up-to-date, but it doesn’t matter since you should be working with the git checkout for the latest version always.

If you’re comfortable with grep that should help find the correct anchors. or of course use your editor’s search across files feature if that’s easier.

Just remember not to fix .html files as they are autogenerated - just ignore those. ipynb are the source.

I’m not sure why you need show_doc, you can just ignore it. When you run the doc notebook show_doc generates the output for each function, but you can’t modify that output anyway, since it’s overwritten. So it’s changing all the other markdown cells that are created manually. And for that purpose you don’t need to run the notebook, just edit and save it. You could even use a text editor to edit it directly instead of jupyter, it’s just more difficult to do.

If you have some specific questions please ask - there is always a chance the guide to doing this can be improved, so please let us know if something wasn’t clear, hard to make sense of/follow, etc.

Oh, one more thing, that I noticed. When I tried to run the script for testing the docs locally, I got an error, which said, that a folder could not be find. Then I changed the path inside the script, which made the script run. However, the result was different compared to the results generated by the non-local test script. Thus, I wondered if the script is broken!? But I assume, I made something wrong (although I think I followed the instructions)!?

If you don’t share the exact commands you attempted to run and the exact errors you received it’s not possible to address this difficulty. Once you do then we can sort it out.

Always remember that when you communicate this-doesn’t-work kind of issue, always put yourself in the shoes of the other person, who doesn’t know neither what this is, nor how it failed.


(Sanyam Bhutani) #88

Hi,
I wanted to ask before making my way to submitting a PR if this is a good idea:

I had presented the fastai image aug using an example and ‘where this might be useful’-application basis.

Link to Kaggle Kernel, I think these would be helpful when going through the docs and understanding for example, how a dihedral transform might be useful.

Looking forward to the feedback.

Regards,
Sanyam


#89

I think we can definitely add a link to this in the docs for vision.transform.


(Sanyam Bhutani) #90

Thanks!
I’ll write a blogpost as well that is more detailed and descriptive and then submit a PR.

Quick question: I couldn’t understand the cases where jitter and random crop might be useful?


(Michael Poli) #91

I’d like to give back to the fastai community to express my gratitude for all the amazing work you guys put in. I decided to start with adding to the docs, which appears to be a task within my reach. Core and torch_core both seem to be missing examples for some of the functions, perhaps I’ll start there since I’m already somewhat familiar with those tools.


(benedikt herudek) #92

check this also @Zymieth How to contribute to fastai [Discussion]


(Michael Poli) #93

Good stuff, your post was really inspiring!


(Michael Poli) #94

A PR for a few functions in fastai core (docs) has been submitted. I started with some of the “simplest” functions to check whether or not you guys think the style is appropriate. Any feedback is appreciated!


#95

It looks great!


(Stas Bekman) #96

@ashaw, would it be possible to adjust docgen to generate consistent font size for the test/source items on the right?
Currently they are included in h1, h2, etc. And you can see from the snapshot result in a weird large/small outcome:

Suggestion: those links shouldn’t be part of the header and use a consistent font. I tweaked it in a saved html and it appears to be fine. it should be the same for all headers.

Thank you.


(Andrew) #97

This is just a notebook problem right?
Definitely fixable, but kind of an ugly hack - adding inline css for only the notebook case.
I’ll play around to see if there’s a cleaner way


(Stas Bekman) #98

No, this is a snapshot from docs.fast.ai. Perhaps re-reading my description again would help - each h1, h2, … has a different font size, so if [test][source] are included in <hX>...</hX> they will be rendered in different sizes as it can be seen from the screenshot.

I proposed to move them out from <hX>...</hX> to keep their size consistent through the document. But perhaps there are other solutions.

Here it is again with circles around it so it’s easy to see the size discrepancy:


(Andrew) #99

Are you not getting the css style then? My docs.fasta.ai looks different


(Stas Bekman) #100

Ah, thank you for that validation, @ashaw - it looks like a problem in the old firefox I use - I re-checked in chrome and it does appear as your snapshot.

So it’s a non-issue. Thanks again.


(Stas Bekman) #101

Can someone improve this doc entry: https://docs.fast.ai/data_block.html#ItemList.get_label_cls
so that the code matches the doc? It doesn’t show how get_label_cls is used.
Thanks.


(George Zhang) #102

I will go through the data block API in the near future and systematically add new examples and fix legacy examples.

Give me a few days.


(Stas Bekman) #103

Thank you, @PegasusWithoutWinds!


(Stas Bekman) #104

A useful thing came out from this discussion with @Kaspar.

We currently hide all import statements in the API nbs. But we should only hide what’s not to be seen, but more precisely we shouldn’t hide the important imports.

So you can see in the modified version of https://docs.fast.ai/utils.ipython.html#utils.ipython
while it still hides the show_doc-related imports it shows the important import:
from fastai.utils.ipython import *

Unless there are objections, I think all API nbs should do that.

Any takers to do it for all nbs?

@ashaw, can we please also modify the doc skeleton generator to create two code cells for imports, one hidden as it is now and another not hidden with just the one line import for that module? as I have done it with https://docs.fast.ai/utils.ipython.html#utils.ipython

update: Discussed this more with the devs, and the agreement is that unless the doc has examples at the top, e.g. https://docs.fast.ai/vision.html, then we want to have the page start with:

“To import the foo module, use:” from foo import *

So here is the model to replicate: https://docs.fast.ai/utils.ipython.html#utils.ipython

screenshot_3


(Stas Bekman) #105

@ashaw, another little thing about anchors.

If you go to: https://docs.fast.ai/utils.ipython.html#utils.ipython it takes you to TOC/h1, and not the utils.ipython entry. so we have a dupe here in tags, since both have the same name.

How can I link to that first h2 utils.ipython entry? e.g. I encountered that in the post above where I was trying to show the import line, but it is taking the reader elsewhere.