Docs review

[stevhliu]

This issue shares some feedback about the latest docs. Really interesting to come back and see what I had written a couple of months ago, let me know what you think! 😅

1. I think the How to integrate upstream/downstream utilities in your library docs describe the download/upload functions themselves more than they describe how-to integrate these functions into a third-party library. The titles and introductions to these docs should be updated to reflect this. It would be more accurate/clear to say something like:

Here are some functions you can use to download or upload files to and from the Hub. You can integrate these functions into your library or use them as-is.

2. For How to integrate upstream utilities in your library, I think this would be better as two separate docs. It's not immediately clear what upstream utilities refer to which could make it difficult for users to find what they're looking for. The doc is also about more than just uploading files to the Hub. Instead, maybe we can have:

• A How to create and manage a repository page to describe how to create, delete, and change repository visibility with huggingface_hub.
• A How to work with repositories and files page to describe the Git-like commands (clone, branch, pull, etc.) methods with the Repository class.

3. Instead of linking to the guide for how to integrate third-party libraries with the Hub, we should have a page in the docs dedicated to it since it is quite important. In general, I think this guide could also be updated because it's not really obvious how to do the actual integration part, except for setting up the Inference API section. There aren't clear steps for how to integrate something like snapshot_download into a third-party library.

   It would be nice to pick a library - spaCy for example - and do a walkthrough on how they integrated huggingface_hub into their library. The catch is spaCy's integration may not be generalizable to all libraries. But I think at least showing this integration process would be really helpful.

A few general housekeeping things I noticed:

1. Link functions to the API reference by using the appropriate format: [hf_hub_url].
2. Wrap some of the code outputs with ``` in Searching the Hub doc.

To do

• Clean up formatting, closed by Tidy up docs #839
• Update how-to guides, in progress in Update how to guides #840
• Create quick start, in progress in Add quick start guide #850
• Update landing page, in progress in Update landing page #854
• Rewrite integration guide

cc @LysandreJik @osanseviero

[osanseviero]

Also cc @NimaBoscarino. For context, this is about huggingface_hub docs, not the Hub docs.

[stevhliu]

Opened #839 to take care of the general maintenance things. Next up, I'll work on something to address 1 and 2 :)

[stevhliu]

Hi sorry for all these PRs! 😅 The plan moving forward is to:

1. Merge the how-to guides.
2. Merge the quick-start guide.
3. Merge the updated landing page with links to all of the above.

For the third-party library integration guide, I don't think doing a step-by-step walkthrough really makes sense anymore because it is so specific to what/how the developer wants to do it. For example, the spaCy push integration looks quite different from the allennlp push integration (at least to my untrained eyes lol). As mentioned in #824, there are two ways to integrate a third-party library and we should center the guides around these:

• Implementing internally in their own library.
• Implementing externally in a separate library.

[osanseviero]

I think the integration part also comes with product changes, so I think we can document this better in the new hub docs revamp, with links to huggingface_hub for pointers in how to do technical things.

[Wauplin]

@stevhliu I'm doing a bit of cleaning in the documentation issues in the repo. I believe all the points in the issue have been addressed. Especially the last point "rewrite integration guide" has been done in #1362 (see guide). Ok for you to close this one?

[stevhliu]

Yeah thanks so much for all the work you've done! 🥳