Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Doc styling #8067

Merged
merged 23 commits into from
Oct 26, 2020
Merged

Doc styling #8067

merged 23 commits into from
Oct 26, 2020

Conversation

sgugger
Copy link
Collaborator

@sgugger sgugger commented Oct 26, 2020

What does this PR do?

This PR introduces a doc styling script and applies it to the repo. The styling script runs similarly to black, with a an option that fixes and overwrites the files (put inside make style) and an option that only checks if there should be a restyle, failing with an error if that's the case (put inside make quality).

The script is applied to all rst files inside docs/source and all py files inside src/transformers. It will look for paragraphs and always reorganize them to use the most of the max_len passed (set at 119 for the repo, like for the code). It will remove all duplicate or trailing whitespace, make all blank lines empty, ignore blocks of code/math and properly take care of the indentation.

A few extra things are performed:

  • making the underline of the titles in rst to the max_len and always adding a blank line after those titles.
  • unifying the format of the triple docstrings in the files
  • always adding a new line before the beginning of a list (because sphinx sometimes complains otherwise)

To make the script ignore a string inside triple quotes (like warnings or long regex expressions), put a # docstyle-ignore somewhere before (it has to be between the previous triple quotes and the ones of the string you want to ignore).

In general, if the script reformats atrociously a docstring, it was because it was badly formatted. Adding a blank line to clearly mark paragraphs can make the script happier. Properly indenting list of arguments (see examples on any of the files of the lib) is also important to get good outputs.

@sgugger sgugger requested a review from LysandreJik October 26, 2020 19:31
@sgugger sgugger merged commit 08f534d into master Oct 26, 2020
@sgugger sgugger deleted the doc_styling_v2 branch October 26, 2020 22:26
@sgugger
Copy link
Collaborator Author

sgugger commented Oct 26, 2020

A few loose-ends to tie, but that will be for tomorrow!

@sgugger sgugger mentioned this pull request Oct 27, 2020
fabiocapsouza pushed a commit to fabiocapsouza/transformers that referenced this pull request Nov 15, 2020
* Important files

* Styling them all

* Revert "Styling them all"

This reverts commit 7d02939.

* Syling them for realsies

* Fix syntax error

* Fix benchmark_utils

* More fixes

* Fix modeling auto and script

* Remove new line

* Fixes

* More fixes

* Fix more files

* Style

* Add FSMT

* More fixes

* More fixes

* More fixes

* More fixes

* Fixes

* More fixes

* More fixes

* Last fixes

* Make sphinx happy
fabiocapsouza added a commit to fabiocapsouza/transformers that referenced this pull request Nov 15, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant