-
Notifications
You must be signed in to change notification settings - Fork 760
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
Use prettier to format the documentation #5708
Conversation
.github/workflows/ci.yml
Outdated
- uses: actions/checkout@v4 | ||
|
||
- name: "Check documentation formatting" | ||
run: npx prettier --prose-wrap always --check docs/*.md docs/concepts/**/*.md docs/guides/**/*.md docs/pip/**/*.md |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why not docs/**/*.md
? Because we need to exclude generated files? This seems brittle.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah, i went with the conservative option here. I have touched neither the reference docs nor the changelog, so i'll follow your lead for them.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Does it support exclusions? Can we encode this in a repo-level config file?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I added exclusion comments. If we have more setting prettier we can switch to one of their configuration files.
I'd like to format the generated files too, but the diff is already large enough.
cf98110
to
0e462a3
Compare
0e462a3
to
7f87842
Compare
7f87842
to
b94bccd
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
SGTM
The pragmas did not work for me
15b6228
to
b4f66e7
Compare
To enforce the 100 character line limit in markdown files introduced in #5635, and to automate the formatting of markdown files, i've added prettier and formatted our markdown files with it.
I've excluded the changelog and the generated references documentation from this for having too many changes, but we can also include them.
I'm not particular on which style we use. My main motivations are (major) not having to reflow markdown files myself anymore and (minor) consistence between all markdown files. I've chosen prettier for similar reason as we chose black, it's a single good style that's automated and shared in the community. I do prefer prettier's style of not breaking inside of a link name though.
This PR is in two parts, the first adds prettier to CI and documents using it, while the second actually formats the docs. When merge conflicts arise, we can drop the last commit and regenerate it with
npx prettier --prose-wrap always --write BENCHMARKS.md CONTRIBUTING.md README.md STYLE.md docs/*.md docs/concepts/**/*.md docs/guides/**/*.md docs/pip/**/*.md
.