[docs] contributing#45465
Conversation
|
The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update. |
vasqu
left a comment
There was a problem hiding this comment.
Submitting part 1 of my review because gh doesnt let me add any more comments for whatever reason. Imo, we should have more eyes on this as the contributing docs are super important imo and I want pretty much the opinion of the whole core team on what their thoughts are
| > [!NOTE] | ||
| > The `preview` command only works with existing doc files. When you add a completely new file, you need to update `_toctree.yml` & restart `preview` command (`ctrl-c` to stop it & call `doc-builder preview ...` again). | ||
| > [!WARNING] | ||
| > `preview` only picks up files that exist when it starts. After you add a brand-new page, update `_toctree.yml` and restart `preview`. `preview` does not work on Windows. |
There was a problem hiding this comment.
Wait actually does not work on win? Shouldn't we mention this on top before watchdog?
There was a problem hiding this comment.
actually, the README is outdated and it should work on Windows thanks to huggingface/doc-builder#351
| Follow the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html) for writing docstrings. | ||
|
|
||
| #### Defining arguments in a method | ||
| ### Defining arguments in a method |
There was a problem hiding this comment.
I might be wrong but is this actually referencing docstrings within modeling_xxx.py/configuration_xxx.py? Or is this really relevant to the docs as well; just seeing that we removed the docs sections itself so this might also not make that much sense
In general, we now have auto docstring which makes things slightly different, e.g. Args: is not really used when auto docstring is involved etc. It might be smarter to reference something along how to write docs within the libraries code base itself which is heavily reliant on auto docs now
There was a problem hiding this comment.
you're right, it makes more sense to reference auto_docstring instead of manual instructions for how to write them
| # Contribute to 🤗 Transformers | ||
|
|
||
| ## Code agent policy | ||
| # Contribute to Transformers |
|
@stevhliu seems like gh is broken and doesnt let me comment anything anymore, can you ping me tomorrow or so again to try again Edit: known issues within GH so will definitely recheck tomorrow In any case cc @huggingface/transformers-core-maintainers to take a look. Docs are not our fav cup of tea I know but I think the contributing docs deserve our time 🫡 |
vasqu
left a comment
There was a problem hiding this comment.
Some additional comments since yesterday I couldnt comment anymore 😢
| 1. [Add a model with modular Transformers](docs/source/en/modular_transformers.md) — implement the model using the modular file and generate standalone modeling files. | ||
| 2. [Add vision processing components](docs/source/en/add_vision_processing_components.md) — add image processors and other vision-specific components if your model requires image inputs. | ||
| 3. [Auto-generate docstrings](docs/source/en/auto_docstring.md) — use the `@auto_docstring` decorator to generate consistent docstrings without boilerplate. | ||
| 4. [Convert checkpoints](docs/source/en/modular_transformers.md#checkpoint-conversion) — write a conversion script to translate upstream weights into a Transformers-compatible format and upload to the Hub. |
There was a problem hiding this comment.
Imo, re weights should be deprecated and only done in special cases --> dynamic weight converter is in general the better way if possible.
There was a problem hiding this comment.
i'll remove this one to direct more focus on the dynamic weight converter
| 7. [Model structure rules](docs/source/en/modeling_rules.md) — check your files pass the static model structure rules enforced by `make typing`. | ||
| 8. [Pull request checks](docs/source/en/pr_checks.md) — understand the Hugging Face CI checks and how to run them locally before opening a PR. |
There was a problem hiding this comment.
Tightly bounded, maybe one suffices?
There was a problem hiding this comment.
the model structure rules one is probably more relevant so i'll keep that one, and it'll also address arthur's comment below
| pytest -q docs/source/en/my_page.md | ||
| pytest -q docs/source/en/ | ||
| ``` | ||
| There are four timelines for model additions depending on the model contributor and community demand for an architecture. |
There was a problem hiding this comment.
I feel like its missing the notes about "to add a model to the transformers familiy you need to make sure you isolate the difference between your model and the recent sota models. This is super helpful for our reviewers to understand what challenges this model brings, and what parts can be standardized.
There was a problem hiding this comment.
added in the ## Adding a new model section above
vasqu
left a comment
There was a problem hiding this comment.
Thanks, this is much nicer! I think we are good to go except @ArthurZucker maybe has something else
I think it's a good choice to properly reference the other guides nowadays to ubloat here
|
merging for now and can update later if there's something else! |
* refactor * writing docs * model addition timeline * feedbacks
docs/README.md