Docs Revamp: new "Repositories" page for hub-docs #92

NimaBoscarino · 2022-04-07T22:01:56Z

This is part of the process of revamping the documentation (#62) + Docs Proposal

This PR contains the first version of the "Repositories" documentation for the Hugging Face Hub, which aims to give readers a introduction to how repos are used in the Hub (for models, datasets, and Spaces) and shows how to get started with cloning, committing, pushing, and more. In-depth git tutorials are offloaded to third-party content. Information in this doc is split into "Getting started", "Best practices", and "Next steps", each covering increasingly complex or niche features.

Note that at the moment everything is contained within a single page, but I think this is a prime candidate for nested pages. Since (as far as I know) Moon Landing doesn't support nested pages for these docs yet, I was thinking that this could start as a single page, then nesting pages could be implemented in Moon Landing, and then this page could be split (probably with each Heading 2 being a separate page). Or the Heading-level split could actually be handled by Moon Landing!

Also note that links to non-existing sections are marked as TODO, and will be patched in a future PR before the revamp release.

Some sections are incomplete.

osanseviero · 2022-04-08T09:54:50Z

Note that at the moment everything is contained within a single page, but I think this is a prime candidate for nested pages. Since (as far as I know) Moon Landing doesn't support nested pages for these docs yet, I was thinking that this could start as a single page, then nesting pages could be implemented in Moon Landing, and then this page could be split (probably with each Heading 2 being a separate page). Or the Heading-level split could actually be handled by Moon Landing!

What we could do for now while developing is:

in /repositories.md, just have something like a Table of Contents. In a follow up PR, from moon landing most likely, we can do some fancy design for it.
and then have a different .md for each of the pages. This won't be in the sections.yml but it will be linked from repositories, so it should be fine. They would still render.

cc @gary149 about this since we'll have to change some UX code for the docs as we were discussing

julien-c · 2022-04-08T11:09:23Z

in my opinion you can already split into nested pages.

the changes required in moon-landing to support this should be super simple, i can do it early next week at the same time (or before) we merge this

osanseviero

This is awesome content, thank you! 🚀 🚀 🚀

docs/hub/repositories.md

osanseviero · 2022-04-08T10:11:10Z

docs/hub/repositories.md

+To be able to push your code to the Hub, you'll need to authenticate somehow. The easiest way to do this is by installing the [`huggingface_hub` CLI](https://huggingface.co/docs/huggingface_hub/index) and running the login command:
+
+```bash
+python -m pip install huggingface_hub
+huggingface-cli login
+```


This will only be required for people that want to do things locally 🤔

For the requirements, instead of having a global "requirements" section, I was wondering if they should be the step 0 for each of the subpages. WDYT?

The subpages that I'm splitting this into are Getting Started, Best Practices, and Next Steps. Would I put this in all 3 sections? I figure that if someone's looking at doing something in the "Best Practices", they would look in "Getting Started" to make sure they'd have the requirements all set.

Or do you think the subpages should be even more granular? e.g. Getting Started > Creating a repo, Getting Started > Cloning repos, etc.

docs/hub/repositories.md

osanseviero · 2022-04-08T11:12:55Z

docs/hub/repositories.md

+### How to use branches
+
+To effectively use Git repos collaboratively and to work on features without releasing premature code you can use **branches**. Branches allow you to separate your "work in progress" code from your "production-ready" code, with the additional benefit of letting multiple people work on a project without frequently conflicting with each others' contributions. To learn about Git branching, you can try out the [Learn Git Branching interactive tutorial](https://learngitbranching.js.org/).
+


Would be cool to have an image here. Maybe @Bibi-O or @gary149 can help creating an illustration for branches.

docs/hub/repositories.md

Splitting a large paragraph into two for easier legibility. Co-authored-by: Omar Sanseviero <[email protected]>

stevhliu

Good intro to repositories! 👍

docs/hub/repositories.md

Suggestions by stevhliu merged in batch from PR review. Co-authored-by: Steven Liu <[email protected]>

NimaBoscarino · 2022-04-13T03:35:31Z

To handle nested pages for the moment I did it with @osanseviero's suggestion of having a table of contents and linking to the pages. I also put the pages into a repositories directory for the moment, but I can adjust it to whichever format would work best for moon-landing, @julien-c ! Any thoughts?

Also, I've applied almost all the feedback (except for moving the images, WIP), so I think this is ready for another round of reviews 😄

stevhliu

The new imgs with the lfs icon look nice! Just a few more minor nits, but otherwise looks good to me 👍

docs/hub/repositories-getting-started.md

Co-authored-by: Steven Liu <[email protected]>

… into revamp/repositories

osanseviero

This looks great to me! Thanks for the PR! 🚀 🚀

Feel free to merge once all comments are addressed. In terms of format, we can always do follow-up PRs to modify once the design decisions are final

osanseviero · 2022-04-15T20:03:52Z

docs/hub/repositories-best-practices.md

+
+<h1>Best practices with repositories</h1>
+
+Here are some additional best practices to help you get the most out of your repository.


Could you please add a section named "Handling multiple experiments" with a large TODO? (I can help with that in a follow-up PR from my side)

I think we can add things from huggingface/huggingface_hub#769 and specially from #53

osanseviero · 2022-04-15T20:04:42Z

docs/hub/repositories-best-practices.md

+ - Other users who visit the URL of your private repo will receive a `404 - Repo not found` error. 
+ - Other users will not be able to clone your repo.
+
+## Security for repositories


Not 100% sure if this is important for the best practices doc. WDYT?

I'm down to remove it, personally! People can always refer to the security docs for info about this stuff.

Yes, I agree

osanseviero · 2022-04-15T20:04:56Z

docs/hub/repositories-best-practices.md

@@ -0,0 +1,27 @@
+---
+title: Getting Started with Repositories


Very nice section!

osanseviero · 2022-04-15T20:08:25Z

docs/hub/repositories-next-steps.md

+
+### Duplicating without Git history
+
+In many scenarios, if you want your own copy of a particular codebase you might not be concerned about the previous Git history. In this case, you can quickly duplicate a repo with the handy [Repo Duplicator](https://huggingface.co/spaces/osanseviero/repo_duplicator)! You'll have to create a User Access Token, which you can read more about in the [security documentation](TODO).


osanseviero · 2022-04-15T20:09:05Z

docs/hub/repositories-next-steps.md

+
+
+## How to programmatically manage repositories
+


Nice reference to huggingface_hub

Add TODO for handling multiple experiments

Add a "Repositories" page with several subpages, outlining how repos are used on the hub, and best practices for creating and maintaining them. Some content remains WIP. Co-authored-by: Omar Sanseviero <[email protected]> Co-authored-by: Steven Liu <[email protected]>

NimaBoscarino added 2 commits April 6, 2022 21:08

WIP: Initial content for repositories

32c6f6d

Some sections are incomplete.

Complete initial content for repositories.

c7ea895

NimaBoscarino requested review from osanseviero and stevhliu April 7, 2022 22:02

NimaBoscarino changed the base branch from main to docs-revamp April 7, 2022 22:03

NimaBoscarino changed the title ~~Docs Revamp: new "Main" page for hub-docs~~ Docs Revamp: new "Repositories" page for hub-docs Apr 7, 2022

osanseviero reviewed Apr 8, 2022

View reviewed changes

Break "What is a repository" into paragraphs

f3ad20c

Splitting a large paragraph into two for easier legibility. Co-authored-by: Omar Sanseviero <[email protected]>

stevhliu reviewed Apr 8, 2022

View reviewed changes

NimaBoscarino and others added 5 commits April 11, 2022 11:16

Code review suggestions: typos and phrasing

c0f4e75

Suggestions by stevhliu merged in batch from PR review. Co-authored-by: Steven Liu <[email protected]>

Adjust git-lfs, commit cycle, and remove unneeded sentence.

f383311

Split into subpages and address some comments

990fc20

Add introductory text to subpages

07f6c93

Add info for extra-large files

a09f97c

NimaBoscarino requested review from osanseviero and stevhliu April 13, 2022 03:35

stevhliu approved these changes Apr 13, 2022

View reviewed changes

NimaBoscarino and others added 4 commits April 13, 2022 10:21

Reformat "Getting started with repos" page

1d00ffd

Apply suggestions from code review

b801e8d

Co-authored-by: Steven Liu <[email protected]>

Address review comments for formatting

eff4554

Merge branch 'revamp/repositories' of github.com:huggingface/hub-docs…

e6b8a18

… into revamp/repositories

osanseviero approved these changes Apr 15, 2022

View reviewed changes

Remove security section

dcbffc8

Add TODO for handling multiple experiments

NimaBoscarino merged commit 239527a into docs-revamp Apr 18, 2022

NimaBoscarino deleted the revamp/repositories branch April 18, 2022 17:30

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs Revamp: new "Repositories" page for hub-docs #92

Docs Revamp: new "Repositories" page for hub-docs #92

NimaBoscarino commented Apr 7, 2022

osanseviero commented Apr 8, 2022

julien-c commented Apr 8, 2022

osanseviero left a comment

osanseviero Apr 8, 2022

NimaBoscarino Apr 13, 2022

osanseviero Apr 8, 2022

stevhliu left a comment

NimaBoscarino commented Apr 13, 2022

stevhliu left a comment

osanseviero left a comment

osanseviero Apr 15, 2022

osanseviero Apr 15, 2022

NimaBoscarino Apr 18, 2022

osanseviero Apr 18, 2022

osanseviero Apr 15, 2022

osanseviero Apr 15, 2022

osanseviero Apr 15, 2022

		### How to use branches

		To effectively use Git repos collaboratively and to work on features without releasing premature code you can use branches. Branches allow you to separate your "work in progress" code from your "production-ready" code, with the additional benefit of letting multiple people work on a project without frequently conflicting with each others' contributions. To learn about Git branching, you can try out the [Learn Git Branching interactive tutorial](https://learngitbranching.js.org/).


		<h1>Best practices with repositories</h1>

		Here are some additional best practices to help you get the most out of your repository.


		### Duplicating without Git history

		In many scenarios, if you want your own copy of a particular codebase you might not be concerned about the previous Git history. In this case, you can quickly duplicate a repo with the handy [Repo Duplicator](https://huggingface.co/spaces/osanseviero/repo_duplicator)! You'll have to create a User Access Token, which you can read more about in the [security documentation](TODO).

Docs Revamp: new "Repositories" page for hub-docs #92

Docs Revamp: new "Repositories" page for hub-docs #92

Conversation

NimaBoscarino commented Apr 7, 2022

osanseviero commented Apr 8, 2022

julien-c commented Apr 8, 2022

osanseviero left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stevhliu left a comment

Choose a reason for hiding this comment

NimaBoscarino commented Apr 13, 2022

stevhliu left a comment

Choose a reason for hiding this comment

osanseviero left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment