API reference documentation #782

LysandreJik · 2022-03-18T13:58:54Z

Work in progress aiming to supply an API reference for the huggingface_hub python library.

Done from a feature branch as many may collaborate on the branch and it will be easier to setup the GitHub Actions CI in a first step.

adrinjalali · 2022-03-18T14:04:16Z

I would appreciate if we setup the CI such that it doesn't require a branch from the same repo, and having the initial PR from a separate repo would make sure the CI runs fine.

If we expect this to be something that multiple people work one, we could have a branch in the repo for it, and have PRs to that branch instead of main, and once we're comfortable with the branch, we can have a single PR to merge it with main. This way multiple people could also send separate PRs to the same branch and there wouldn't be conflicts between their work for working on the same branch.

LysandreJik · 2022-03-18T14:30:41Z

Regarding the CI: yes, that is the goal, but it is not ready right now and needs iteration, which I hope to do right here.

Regarding the second point, I'm not sure I understand; that is absolutely the goal as well. I am creating an initial commit on a feature branch, which takes care of most of the work. As you can see, it is not yet ready as the CI did not run, a very important step in order to collaborate on this specific branch.

We can then work on that branch through PRs as you mention, once I set this branch as ready for contributions.

How would you have managed this differently?

adrinjalali · 2022-03-18T14:32:54Z

Fair enough. I though you meant for people to directly push to this branch. I'm happy if people push to this branch through PRs from their forks.

I would create a branch with no changes, and then create a PR from my fork to that branch with the initial changes you're proposing here. But that's a minor difference. I'm happy with what you propose :)

HuggingFaceDocBuilderDev · 2022-03-23T13:02:37Z

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint.

LysandreJik · 2022-03-23T13:02:58Z

adrinjalali · 2022-03-23T13:17:21Z

We should be good to go to work on this feature branch now.

Not sure if I understand. So you mean we can now send PRs to this branch?

LysandreJik · 2022-03-23T13:25:33Z

Yes, that's what I mean!

LysandreJik · 2022-03-24T15:16:22Z

Opened a first PR here which takes care of all the remaining methods mentioned above: #799

adrinjalali

Same with long lines and hyperlink issues here.

docs/source/package_reference/hf_api.mdx

* Finalize docstrings * Endpoint helpers * Run on doc-frontend target * It was just another GitHub Actions issue * Address review comments Co-authored-by: Adrin Jalali <adrin.jalali@gmail.com> * Address review comments * Add deprecation warnings * Precise deprecation warnings Co-authored-by: Adrin Jalali <adrin.jalali@gmail.com>

LysandreJik · 2022-03-29T13:42:47Z

PR was merged, but GitHub Actions didn't launch the workflow (it seems to be down) to update the documentation yet, please be aware of it when reviewing if checking the documentation.

Since the delete documentation didn't launch either, the documentation of this PR with the commit above can be seen here

LysandreJik · 2022-03-29T13:45:13Z

@stevhliu, @osanseviero, could you take a look at this PR? Would love to hear your feedback about the content.

This will likely be put at https://huggingface.co/docs/python-wrapper

osanseviero

Very nice, thank you for this PR! I did a pass through most files (missing repository and endpoint_helpers to make sure they are consistent.

docs/source/package_reference/mixins.mdx

src/huggingface_hub/hf_api.py

src/huggingface_hub/keras_mixin.py

src/huggingface_hub/utils/logging.py

stevhliu

This is great, I learned a lot from reading this! 🎉

What do you think about adding a brief code example for each function like you already have for the DatasetFilter section? This could help cover functions/methods we don't explicitly cover in the tutorials/guides (maybe because they aren't commonly used but they're still useful).

It'd be quite a bit to add though so we can always tackle it in a later PR. ❤️

docs/source/package_reference/hf_api.mdx

docs/source/package_reference/logging.mdx

src/huggingface_hub/utils/endpoint_helpers.py

Co-authored-by: Steven Liu <59462357+stevhliu@users.noreply.github.com> Co-authored-by: Omar Sanseviero <osanseviero@gmail.com>

julien-c · 2022-03-30T08:47:10Z

This will likely be put at https://huggingface.co/docs/python-wrapper

For consistency I would rather serve the doc at https://huggingface.co/docs/huggingface_hub, but add "Client library" or "Python wrapper" to the titles etc so it's not confusing. Thoughts?

LysandreJik · 2022-03-30T09:40:10Z

This PR should be ready to be merged.

When merged, I would like to open issues for the following:

On doc-builder, open issues to ask for support of a few items:
- Different colors for <Tip>, which should have different severity levels
- Mention that in-parameter-docstrings doesn't support code samples
- Raises and Yields are not rendered correctly
- versionadded and other directives that would have been useful
On huggingface_hub, open issues to track the following:
- Lack of images right now, and definition of a way to provide images to the hub

If this looks good to you, @osanseviero @stevhliu, I'll merge this PR.

coyotte508 · 2022-03-31T08:42:38Z

docs/source/_toctree.yml

@@ -0,0 +1,24 @@
+- sections:


I think a title should also be added here (like below with title: "Reference").

https://moon-ci-docs.huggingface.co/docs/huggingface_hub/pr_782/en/index

Indeed, good catch! Will add this.

adrinjalali

Happy to merge and improve on smaller PRs. This is already too large.

osanseviero

This is great, thanks!

LysandreJik · 2022-03-31T10:04:20Z

Thanks all for the reviews, all green, merging this PR! Will open a few relevant issues as discussed above.

New documentation

dc6ce03

push -> pull_request workflow trigger event

7e30c6e

LysandreJik mentioned this pull request Mar 24, 2022

Replace obsolete function argument name in docs for api.create_repo #795

Closed

adrinjalali reviewed Mar 25, 2022

View reviewed changes

docs/source/package_reference/hf_api.mdx Outdated Show resolved Hide resolved

docs/source/package_reference/hf_api.mdx Outdated Show resolved Hide resolved

LysandreJik and others added 2 commits March 29, 2022 09:34

Fix workflow launch

2eb4581

osanseviero reviewed Mar 29, 2022

View reviewed changes

stevhliu reviewed Mar 29, 2022

View reviewed changes

Apply suggestions from code review

673ec21

Co-authored-by: Steven Liu <59462357+stevhliu@users.noreply.github.com> Co-authored-by: Omar Sanseviero <osanseviero@gmail.com>

Apply review comments

218a6f2

LysandreJik marked this pull request as ready for review March 30, 2022 09:31

Merge branch 'main' into doc-frontend

f0524e0

stevhliu mentioned this pull request Mar 30, 2022

Non-unique anchor tags huggingface/doc-builder#168

Closed

adrinjalali added this to the v0.4 milestone Mar 31, 2022

LysandreJik mentioned this pull request Mar 31, 2022

Uniformize hf_api a bit and add support for Spaces #792

Merged

coyotte508 reviewed Mar 31, 2022

View reviewed changes

adrinjalali approved these changes Mar 31, 2022

View reviewed changes

Add missing title to section

464babb

osanseviero approved these changes Mar 31, 2022

View reviewed changes

LysandreJik merged commit 3e72bc8 into main Mar 31, 2022

LysandreJik deleted the doc-frontend branch March 31, 2022 10:04

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API reference documentation #782

API reference documentation #782

LysandreJik commented Mar 18, 2022

adrinjalali commented Mar 18, 2022

LysandreJik commented Mar 18, 2022

adrinjalali commented Mar 18, 2022

HuggingFaceDocBuilderDev commented Mar 23, 2022

LysandreJik commented Mar 23, 2022 •

edited

Loading

adrinjalali commented Mar 23, 2022

LysandreJik commented Mar 23, 2022

LysandreJik commented Mar 24, 2022

adrinjalali left a comment

LysandreJik commented Mar 29, 2022

LysandreJik commented Mar 29, 2022 •

edited

Loading

osanseviero left a comment

stevhliu left a comment

julien-c commented Mar 30, 2022

LysandreJik commented Mar 30, 2022 •

edited

Loading

coyotte508 Mar 31, 2022 •

edited

Loading

LysandreJik Mar 31, 2022

adrinjalali left a comment

osanseviero left a comment

LysandreJik commented Mar 31, 2022

API reference documentation #782

API reference documentation #782

Conversation

LysandreJik commented Mar 18, 2022

adrinjalali commented Mar 18, 2022

LysandreJik commented Mar 18, 2022

adrinjalali commented Mar 18, 2022

HuggingFaceDocBuilderDev commented Mar 23, 2022

LysandreJik commented Mar 23, 2022 • edited Loading

adrinjalali commented Mar 23, 2022

LysandreJik commented Mar 23, 2022

LysandreJik commented Mar 24, 2022

adrinjalali left a comment

Choose a reason for hiding this comment

LysandreJik commented Mar 29, 2022

LysandreJik commented Mar 29, 2022 • edited Loading

osanseviero left a comment

Choose a reason for hiding this comment

stevhliu left a comment

Choose a reason for hiding this comment

julien-c commented Mar 30, 2022

LysandreJik commented Mar 30, 2022 • edited Loading

coyotte508 Mar 31, 2022 • edited Loading

Choose a reason for hiding this comment

LysandreJik Mar 31, 2022

Choose a reason for hiding this comment

adrinjalali left a comment

Choose a reason for hiding this comment

osanseviero left a comment

Choose a reason for hiding this comment

LysandreJik commented Mar 31, 2022

LysandreJik commented Mar 23, 2022 •

edited

Loading

LysandreJik commented Mar 29, 2022 •

edited

Loading

LysandreJik commented Mar 30, 2022 •

edited

Loading

coyotte508 Mar 31, 2022 •

edited

Loading