Documentation improvements

fastai
9

Like I said, more examples. Pages outlined contain only functions with a short description (in the worst cases). Showing an example of how to use each of them is kind of what we’re looking for.

2 Likes
10

I’ll try to work on the callbacks page :slight_smile:

Do you have any pointers on what could be improved ?

11

To be sure I fully understand what you asked for Sylvain : you want examples for each callbacks on the callback page ?
Would taking parts of existing callbacks like LRFinder to illustrate the use of the different methods be a good way to go ?

12

I was meaning the callback overview page callbacks. It is a little different since it doesn’t actually document functions, but is an overview. A very good overview is the training overview so you can definitely inspire yourself from it.
The callback page is fine IMO.

13

All right, I’m gonna try to do something similar :slight_smile:

14

Hi All - this is a really silly question, but where can one start a new post? I can’t find anywhere how to create a new post?

15

You mean on the forum ? Top right, “new topic”

16

Hi,

I am new to this community and want to contribute to this documentation part as a result I would get a chance to look at the source code of fastai and get a much better understanding of the library. (NB: I was not able to take Fast.ai course Part 1 v3).

I have some minor doubts here regarding the task:

  • I decided to take up the torch_core docs. To be clear I should be writing docs for torch_core right?
  • I started looking at the notebook and found out show_doc(flatten_model, full_name='flatten'). Which shows flatten_model as flatten. I am not sure why flatten_model has to be shown as flatten, I did not find any call to flatten in the fastai library. Please help me understand this. (Sorry if this is an obvious thing)
17

You should modify the notebook torch_core.ipynb in the docs_src folder, yes. What you found is a bug, so you should remove that full_name argument (guessing it’s legacy code for when the function was named differently).

1 Like
18

Yes, you are right! But I think the solution is to replace the call as show_doc(flatten_model, full_name='flatten_model'). As get_anchor which gets called inside show_doc returns '<lambda>' for lambda functions instead of their names, and I guess that is the expected behavior.

Anyways, thanks for the reply. I am on my way to documenting it. :slight_smile:

19

That must be it. We changed the function name and forgot to update the name here.

20

Hi again,

So, I started documenting the torch_core, and need some feedback and help. I have listed them bellow:

  1. I tried to document model2half, np2model_tensor. Please have a look here at my fork to see the changes. Just needed your feedback on how good/bad are these, what could be improved, or how else you had it in mind, am I missing something, etc.

  2. How should I provide an example for model2half. Any ideas? Maybe somehow showing the memory usage of models with and without fp16?

  3. Should I be changing function docs in the torch_core.py file? Cause in some cases it is difficult for me to understand. e.g. in requires_grad, the function doc seems ambiguous or even incorrect to what the function is actually doing. It says

    "If `b` is not set `requires_grad` on all params in `m`, else return `requires_grad` of first param."

    Whereas, I think something like below makes more sense:

    "If `b` is not set return `requires_grad` of first param, else set `requires_grad` on all params in `m` as `b`"

    What should I do in such cases :thinking:

  4. I found no reference calls for np2model_tensor in the fastai codebase, and I have a feeling that tensor performs something similar, and even more than np2model_tensor. Is there a redundancy here?

  5. Also, I know these are very small issues and I should not waste your time in this, just wanted to ask in future if I get more doubts like above, should I be posting in this thread or a separate new thread? :confused:

Thanks in advance, :slight_smile:
NVS Abhilash

21
  1. That seems pretty much what we need!
  2. Just define a simple model with conv layer and batchnorm layer then show how it was changed by model2half is enough, I gues
  3. Yes if the 1-line doc strings aren’t clear enough feel free to change them (note that they should take one line or less, any additional details are for the doc page)
  4. It might be some legacy code we forgot to clean, let me check with Jeremy
  5. I think it’s fine to post them in this thread as any person that has some doubts about what to do to contribute to the docs could see it.

Thanks for your help!

1 Like
23

About the callbacks overview section : would you rather have an example of use of the actual callbacks (like LRFinder for example) or, when possible, an example of the built-in function that uses that callback (lr_find in the same example) ?

Also I saw 2 show_doc() functions visible in the actual documentation pages (here’s one just above the linked section). I think they are not supposed to be shown, but I don’t know how to fix it. Do I just mention the instances here ?

24

Yes the show_doc are supposed to be hidden. You need to install nbcontrib extensions:

pip install jupyter_contrib_nbextensions
jupyter contrib nbextension install --user

then activate the hide_input extension (as shown here). You can point us to them but we’ll likely forget so it’s best if you make a simple PR to fix them.

1 Like
25

Hi,
I’d like to help, but am finding it difficult to distill the process I should follow from the various threads on the forum.
I think I need to familiarize myself with the fastai pull request protocol and the contributing to docs process. Can you please confirm?
Thanks

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.

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.

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
1 Like
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: