[Docs] Model_doc structure/clarity improvements by MKhalusova · Pull Request #26876 · huggingface/transformers

MKhalusova · 2023-10-17T18:08:47Z

This PR streamlines pages in model_doc, so that a user who has seen at least one of these pages, should find it easier to navigate throughout any other model_doc page. These are the changes:

Individual pages now have (with a few exceptions) the same structure: overview, followed by author acknowledgement, usage tips and/or examples, resources (other docs, notebooks, blog posts, etc.), API reference (autodoc). Previously, some pages did not have the same order which could make searching through them confusing.
Usage tips now have their own section with a header. Previously, they often have been buried within the overview section, now one can find them faster.
In cases where a model has the same architecture as another model, a visible <Tip> has been added with a link to API reference of the original model.
“Documentation resources” and “resources” were combined into “Resources”
For models that support TF and JAX, a <framework> tag was added so that a user could collapse sections irrelevant to them.
Removed disclaimers like “This model has been recently added. If you see something strange, file a GitHub Issue” for models that have been in the library longer than 1 year.

The PR aims to:

Make it easier to find usage tips and examples
Make it easier to find API reference for models that are based on another model’s architecture
Possibly reduce the bloat by letting the users collapse framework-specific sections
Streamline the model_doc pages structure

HuggingFaceDocBuilderDev · 2023-10-23T18:18:19Z

The documentation is not available anymore as the PR was closed or merged.

stevhliu

Wow really nice! 🎉 I love the idea of standardizing the pages so it's more consistent when going from model page to model page.

MKhalusova · 2023-10-31T14:53:20Z

If @ArthurZucker is busy, maybe @amyeroberts could take a look?

amyeroberts

Mammoth piece of work! Thanks for all of this effort in making our documentation better ❤️

Main comment is about the tips for vision models mentioning the image processors. I realise this isn't something you added (I've approved in PRs) - it's just now in the refactoring and moving to tips I see it's not needed.

amyeroberts · 2023-11-02T18:34:32Z

docs/source/en/model_doc/videomae.md

+<Tip>
+
+Use [`VideoMAEImageProcessor`] to prepare videos for the model. It will resize + normalize all frames of a video for you.
+</Tip>


I'm not sure whether we need this tip. All the processing classes (tokenizers, image processors, feature extractors etc.) prepare the raw data for the model

amyeroberts · 2023-11-02T18:42:50Z

docs/source/en/model_doc/bit.md

 [[autodoc]] BitForImageClassification
    - forward
-
+    


Suggested change

amyeroberts · 2023-11-02T18:51:56Z

docs/source/en/model_doc/deformable_detr.md


+## Usage tips
+
+- Use [`DeformableDetrImageProcessor`] to prepare images (and optional targets) for the model.


I'm not sure we need this tip - this is true for all vision models and their image processors

Good point, I'll address this.

amyeroberts · 2023-11-02T18:52:38Z

docs/source/en/model_doc/deta.md


+<Tip>
+
+Use [`DetaImageProcessor`] to prepare images and optional targets for the model.


Same here re needing the tip

amyeroberts · 2023-11-02T18:55:27Z

docs/source/en/model_doc/focalnet.md

+<Tip>
+
+Use the [`AutoImageProcessor`] class to prepare images for the model.
+</Tip>


amyeroberts · 2023-11-02T19:07:07Z

docs/source/en/model_doc/swinv2.md


 If you're interested in submitting a resource to be included here, please feel free to open a Pull Request and we'll review it! The resource should ideally demonstrate something new instead of duplicating an existing resource.

+<Tip>


amyeroberts · 2023-11-02T19:47:11Z

docs/source/en/model_doc/timesformer.md

-Tips:
-
-There are many pretrained variants. Select your pretrained model based on the dataset it is trained on. Moreover, the number of input frames per clip changes based on the model size so you should consider this parameter while selecting your pretrained model.
+There are many pretrained variants. Select your pretrained model based on the dataset it is trained on. Moreover,


This seems like it falls under a useage tip

Thanks for noticing! I missed this one.

amyeroberts · 2023-11-02T19:47:31Z

docs/source/en/model_doc/table-transformer.md

 - A demo notebook for the Table Transformer can be found [here](https://github.com/NielsRogge/Transformers-Tutorials/tree/master/Table%20Transformer).
 - It turns out padding of images is quite important for detection. An interesting Github thread with replies from the authors can be found [here](https://github.com/microsoft/table-transformer/issues/68).

+<Tip>


amyeroberts · 2023-11-02T20:00:33Z

docs/source/en/model_doc/dinat.md


 If you're interested in submitting a resource to be included here, please feel free to open a Pull Request and we'll review it! The resource should ideally demonstrate something new instead of duplicating an existing resource.

+<Tip>


amyeroberts · 2023-11-02T20:00:43Z

docs/source/en/model_doc/dinov2.md

 This model was contributed by [nielsr](https://huggingface.co/nielsr).
 The original code can be found [here](https://github.com/facebookresearch/dinov2).

+<Tip>


* first batch of structure improvements for model_docs * second batch of structure improvements for model_docs * more structure improvements for model_docs * more structure improvements for model_docs * structure improvements for cv model_docs * more structural refactoring * addressed feedback about image processors

first batch of structure improvements for model_docs

17b2c3d

MKhalusova marked this pull request as ready for review October 17, 2023 18:31

MKhalusova marked this pull request as draft October 17, 2023 18:32

MKhalusova added 6 commits October 18, 2023 08:48

second batch of structure improvements for model_docs

90b52eb

more structure improvements for model_docs

c589584

more structure improvements for model_docs

5bda56b

structure improvements for cv model_docs

223e890

more structural refactoring

3650998

Merge branch 'main' into model_doc_cleanup

ea5f19d

MKhalusova marked this pull request as ready for review October 24, 2023 11:55

MKhalusova requested review from ArthurZucker and stevhliu October 24, 2023 11:55

stevhliu approved these changes Oct 26, 2023

View reviewed changes

amyeroberts approved these changes Nov 2, 2023

View reviewed changes

addressed feedback about image processors

685d35b

MKhalusova merged commit 5964f82 into huggingface:main Nov 3, 2023

amyeroberts mentioned this pull request Nov 8, 2023

[time series] Add PatchTST #25927

Merged

4 tasks

kashif mentioned this pull request Nov 13, 2023

[Docs] PatchTST doc improvements #27476

Closed

stevhliu mentioned this pull request Nov 15, 2023

Translate en/model_doc to JP #27264

Merged

amyeroberts mentioned this pull request Nov 15, 2023

TVP model #25856

Merged

amyeroberts mentioned this pull request Nov 20, 2023

Add Beit3 model #22289

Closed


		## Usage tips

		- Use [`DeformableDetrImageProcessor`] to prepare images (and optional targets) for the model.


		<Tip>

		Use [`DetaImageProcessor`] to prepare images and optional targets for the model.


		If you're interested in submitting a resource to be included here, please feel free to open a Pull Request and we'll review it! The resource should ideally demonstrate something new instead of duplicating an existing resource.

		<Tip>

Conversation

MKhalusova commented Oct 17, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

HuggingFaceDocBuilderDev commented Oct 23, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stevhliu left a comment

Choose a reason for hiding this comment

Uh oh!

MKhalusova commented Oct 31, 2023

Uh oh!

amyeroberts left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

MKhalusova commented Oct 17, 2023 •

edited

Loading

HuggingFaceDocBuilderDev commented Oct 23, 2023 •

edited

Loading