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

Use prettier to format the documentation #5708

Merged
merged 6 commits into from
Aug 2, 2024
Merged

Use prettier to format the documentation #5708

merged 6 commits into from
Aug 2, 2024

Conversation

konstin
Copy link
Member

@konstin konstin commented Aug 1, 2024

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.

@konstin konstin added the documentation Improvements or additions to documentation label Aug 1, 2024
- 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
Copy link
Member

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.

Copy link
Member Author

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.

Copy link
Member

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?

Copy link
Member Author

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.

@zanieb zanieb added the internal A refactor or improvement that is not user-facing label Aug 1, 2024
@konstin
Copy link
Member Author

konstin commented Aug 1, 2024

For the jetbrains IDE users, you can configure prettier to run for *.md on save instead of the default formatter. Don't forget to make sure that node is also configured.

image

Copy link
Member

@BurntSushi BurntSushi left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SGTM

@zanieb zanieb merged commit db37156 into main Aug 2, 2024
57 checks passed
@zanieb zanieb deleted the konsti/format-docs branch August 2, 2024 13:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation internal A refactor or improvement that is not user-facing
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants