How to contribute to the fast.ai docs?

Hi @jeremy

I was studying the docs and I’ve noticed most_confused function is missing there.

Could you tell me how to add it?

Thanks!

1 Like

If you download the corresponding notebook, you can find how all the other docs are shown. I’m pretty sure you’ll find this function at the end in a section ‘Not yet documented’ that isn’t converted to HTML.
There is also the docs on how to contribute to the docs.

PS: please remember not to @ people when other can also answer your question :wink:

1 Like

I actually asked him to do so, so I didn’t miss this. So thanks to both of you for being extra helpful here! :smiley:

1 Like

We probably need to work to make that more accessible. Currently I’m not sure it really answers the question “how do I contribute to the docs”. Instead it’s got lots of details about specific areas, but no overview. So how about this @ibacaraujo - I’ll explain the steps here, and then you can make your first contribution to the docs to be adding this to the link that @sgugger provided?

Quick guide

One-time setup

  1. Enable the Hide Input jupyter extension
  2. Clone the docs repo
  3. In the repo: cd docs_src. All the notebooks are there. Look for one with the same name as the html file you want to change
  4. Run tools/run-after-git-clone

Changing a notebook

  1. Run jupyter notebook in the directory, and open the notebook identified above
  2. Make whatever changes you wish. (You should find undocumented functions in cells at the end of the notebook. Move them to the appropriate section)
  3. Save the notebook, then back in your terminal run tools/sgen_notebooks.py filename.ipynb (replacing filename of course)
  4. There is now an html file in the docs/ directory of the repo. This directory is a standard jekyll site - install jekyll to view it and check it looks ok. See here for help installing jekyll
  5. Once it looks OK, go ahead and submit a PR. We recommend using hub

Tips

  • Try to always include a working example of the function being used - i.e. an actual code cell with actual output. Plots are most welcome too. This is why we use notebooks!
  • We use the show_doc function to create the basic function/class signature for the function - this should be handled automatically for you. The actual call to show_doc is hidden, using the ‘Hide Input’ extension
4 Likes

Thank you for the answer, @sgugger!

Really great, @jeremy! Thank you very much for the guide. I will work on this!

1 Like

What is the best way to contribute to the fast.ai library? When I was reading the fast.ai developer docs, I found the whole process a little overwhelming. I am wondering if anyone has any best practices other than using hub as Jeremy described above.

That being said I was working on lesson one v3 and I was thinking a small semantic change in the description of plot_top_losses could make it easier for novices to understand plot if the description was more closely aligned with the output.

Current description:

“Show images in top_losses along with their loss, label, and prediction.”

Proposed description:

“Show images in top_losses along with their prediction, actual, loss, and probability of actual class.”

In general, what type of PR’s does the industry find most beneficial? Would you recommend this type of semantics push request? Since they could come across critical, opposed to helpful.

You can make a direct pull request to correct small typos, grammatical errors (a lot of people that work on the library don’t have English as a native language) or change the docs one-liners to be clearer.
If we disagree with the change, we’ll let you know, but we never take those kinds of PR as critical (can’t speak for other projects but I don’t see why they would).

2 Likes

Could you let us know which parts you found overwhelming? I’d love to see if I can make it more accessible.

In general, the answer to your question is - just do your best, tell us here any time you get stuck, and we’ll try to help you. We appreciate all PRs, since they show that someone cares enough about our work to want to help improve it. If we reject a PR, we’ll let you know why - and hopefully that’s a useful process for everyone too! :slight_smile:

Unfortunately I can’t tell you the specific parts of the developer docs that caused my confusion. I think my problem is I don’t have any real world experience with all the nuances of git, and version controls. Frankly I had no idea how much there was so much to it, I think it just caught me off guard. I thought it was just push, pull, and clone. Reading the dev docs is kind of like reading a different language, my brain just shut down.:exploding_head:. I will learn it all soon, but I will have to put in some time to learn it. Maybe then I can give you a better answer.

One of the reasons I love the fast.ai way, is it forces me to learn so much more than just the fast.ai library. I have learned about bash, terminal, linux, notebooks, curl, AWS, computer hardware, vim, tmux, debugger, pytorch, and so much more.

Thank you so much for the time you have put into fast.ai and the deep learning community. You have made it possible for me to follow my dream to make the world a better place. Without your efforts and teaching style, I would still be in a master’s program that wouldn’t have given me a fraction the knowledge I have today. It is your leadership that gives me the energy to wake up at 4am everyday and learn.

Cheers! :beers:

2 Likes

I have been working on the docs and I am in this step to run tools/sgen_notebooks.py, but the file is not there. Has this file been replaced by build-docs?

I think the issue is actually our dev docs. Currently we don’t have many simple walk-thrus, but instead have very complete details, with lots of jargon etc. Mainly the dev docs have been written with our own team in mind so far, not beginners.

So please don’t be put off. Instead, pick one small thing you’d like to do. Tell us what it is. We’ll tell you how to do it - or at least set you on the right direction.

Remember: trying to understand every detail of anything when you start is always going to be intimidating - and is rarely if ever necessary! :slight_smile:

1 Like

I believe it’s been moved to tools/update-nbs . There’s a comment at the top with info.

1 Like

When running tools/update-nbs docs_src/vision.learner.ipynb:

I couldn’t find a solution for this. Besides, when I try to install jekyll using bundle install jekyll, the following message is shown:

ERROR: "bundle install" was called with arguments ["jekyll"] Usage: "bundle install [OPTIONS]"

Thanks!

We’ll take a look. One thing that might help - try doing the “developer install” mentioned in the fastai readme.

I am happy to say that I submitted my first PR this morning, and it was accepted/merged this morning! I was so excited!
:beers:

3 Likes

Wonderful. Could you tell us a bit about the process you used, and what you learned, to help other folks interested in making their first contribution?

I used the GitHub desktop, github.com, and visual studio code(any text editor should work).

  1. GitHub
    Make sure you are logged in to your GitHub account. (sign up or sign in )

  2. GitHub Desktop
    Download(windows or macOS) or open GitHub Desktop

  3. Tutorials
    If you are new to GitHub, a good place to start is GitHub’s “Hello World” tutorial it cover some of the features/terms you are going to need to know(What is GitHub?, Create a Repository(Repo, Create a Branch, Make a Commit, Open a Pull Request(PR), Merge Pull Request). Some other options are hubspot’s git-and-github-tutorial-for-beginners, or github-flow

  4. Clone & Fork
    I chose to Clone as well as fork the fastai GitHub repo. The reason I chose to do this is I could use the official GitHub repo for reading/class-work, and use the forked one to make my proposed change(s) to the library.

  5. Clone It


    To me cloning a repo is like borrowing a library book, it is possible to make changes/commits(write in it) when it is in your possession, but changes you make could cause problems/errors(conflicts) since you don’t have permission to make changes/updates. The changes you make will only be on your local copy, and if you try to return-it/update-it, it might cause issues. Since most library and companies have a code review process, you can’t create a pull request(PR) from a cloned copy. You need to do that from a Forked copy.

  6. Fork It


    As time goes by, chages will be made to the fastai library, and you will need to update your forked copy with the new updates by syncing the fork. If you very recently forked the repo you won’t have to worry about this, but if it has been more than a couple days you will most likely want to update it before making your changes. See the fastai-docs “start-with-a-synced-fork-checkout” and syncing-“subsequent-times”, personally I think it is easier for the beginner to just use GitHub-desktop to get updates/sync-fork.

Tip - You probably want a unique name for your fork because if you use fastai, it can be confusing because fastai/fastai and YourGitHubUserName/fastai will both show as fastai in the current repository section

  1. Open GitHub-desktop


    Every repo has a “master” “branch”, this is your main version. The “repository”(repo) could be the source, or it could be a “fork” of that source. The source(repo forked from) is considered to be"upstream", its main version would be considered “upstream/master”.

  2. Checking for updates/changes/syncing-fork


  3. Branches
    Branches are a very important part of the git/github process. Generally speaking, you want to create a new branch for each new feature.

Fastai dev docs:
“It’s very important that you always work inside a branch . If you make any commits into the master branch, you will not be able to make more than one PR at the same time, and you will not be able to synchronize your forked master branch with the original without doing a reset. If you made a mistake and committed to the master branch, it’s not the end of the world, it’s just that you made your life more complicated. This guide will explain how to deal with this situation.”

  1. Make your changes in the text editor of your choice
    Github-desktop tracks the local folder that your repo is in, and if you make any changes to the files or folder in that folder, GitHub-desktop keeps track of all the changes, so when you log back into GitHub-desktop, it knows what needs to be committed/updated.

    Once you commit to master, It will now be updated/committed on github.com as well. You can then submit a Pull Request on gitHub.com, in GitHub-Desktop, or in the terminal.

Keep in mind if you are updating the Jupiter-notebooks(docs) you will need to perform additional steps.

  1. Pull Request via GitHub.com
    Log-in to github.com, go into your forked repo.

    Compare changes

    Add in description and documentation

More information is available in the fastai developer documentation

Now Git to It!

12 Likes

Great tutorial! Would you mind making a proper markdown file out of it, and we could add it to the tutorials on course-v3 if Jeremy is okay with it?

1 Like

I would love to! :slight_smile:

@Daniel.R.Armstrong - if you do this, you can send a PR here : https://github.com/fastai/fastai/tree/master/docs

You should create a new subfolder inside the “images” folder, eg “images/pr_tutorial”. You can copy your images there (if you don’t have a local copy, you can grab them from the URLs in your post, by editing it). Then paste your post markdown into a file - e.g. “pr_tutorial.md”. You can use a markdown gui tool on your computer to check it all looks OK.

2 Likes

I would be happy to do that!

1 Like