Documentation improvements

fastai
1

I just went through a huge proofread and update of the docs of fastai and there are quite a few of them that could be improved.

need_you

If you’re looking to help a bit with fast.ai while learning a little bit more about how the library works before part 2 of the course, this is a very good thing to look into. All the functions are properly documented but in some cases, we’re seriously lacking some examples (sometimes a lot of them). it doesn’t need to be super-evolved, but just a little example of what the function does, that runs fast (we’re using all the docs notebooks for tests). For instance vision transforms is a great doc page for this.

You don’t need to be an expert, just figuring out how the function works by playing with it, highlighting some unexpected behavior or difficulties you had adding a little more descriptions of what an argument does if needed, all of this would be great.

Here are the pages I think could really be improved (this list will be updated as things improve or new pages arrive):

  • callbacks.rnn
  • core (severely lacking)
  • callbacks
  • basic_data
  • datasets
  • layers (second half)
  • metrics
  • overview
  • tabular.models
  • tabular.transform
  • text.data (in the beginning)
  • torch_core (severely lacking)
  • vision.gan
  • vision.models
  • vision.models.unet
  • vision.transform pre-run resize methods

You can do just one function in one of them, I’m not making this topic a wiki with people putting their names in front of one page because I think small incremental progress is going to be more efficient, so don’t be afraid!

Compiling useful information posted in the forums and putting it in the docs would make for an extremely useful contribution, for some ideas see this post.

Feel free to use this topic to ask any questions you might have around the process or to suggest additional content that could be made better.

broken links

docs generator improvements:

  • None

website improvements:

Process for contributing to the docs

You will find the full instructions/explanations on how to author docs here:
https://docs.fast.ai/gen_doc_main.html#process-for-contributing-to-the-docs

Notes

show_doc entries

show_doc are supposed to be hidden. You need to install `jupyter_contrib_nbextensions:

pip install jupyter_contrib_nbextensions
jupyter contrib nbextension install --user
# then restart jupyter notebook

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.

This is a wiki post, so please feel free to improve it.

34 Likes
2
7

I added this project to the Index, and made you a coordinator @sgugger!

1 Like
8

I’d like to work on text.data. Could you outline what exactly you are looking for here?

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