Skip to content

Doc styling#8067

Merged
sgugger merged 23 commits intomasterfrom
doc_styling_v2
Oct 26, 2020
Merged

Doc styling#8067
sgugger merged 23 commits intomasterfrom
doc_styling_v2

Conversation

@sgugger
Copy link
Copy Markdown
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
Copy Markdown
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
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