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

[Tidy] Apply mdformat to markdown files #873

Merged
merged 66 commits into from
Dec 4, 2024
Merged

[Tidy] Apply mdformat to markdown files #873

merged 66 commits into from
Dec 4, 2024

Conversation

antonymilne
Copy link
Contributor

@antonymilne antonymilne commented Nov 14, 2024

Description

Technical reviewers, please look at the built HTML rather than the diffs, since there are a lot of files changed in small fiddly pointless ways to appease mdformat.

Please focus on checking things like admonitions (do they still look as they should) and code snippets: are they OK?

Background from @antonymilne

Initial step towards #719 which actually formats very little of our code and instead applies a general markdown linter across our whole repo. Code formatting will follow in a later PR.

I have played around with various mdformat options and plugins for quite a long time now and I still do not fully understand how it behaves, which make me feel a bit uneasy... But it did help catch several errors in our yaml and seems to have done a generally good job tidying things up.

The most controversial change (which is responsible for 90% of the diff) is that I set keep=no to remove word wrapping. This is something I've wanted to do for a long time (just use word wrapping in your editor with whatever width you like) but I am not strongly wedded to it if others disagree. wdyt @stichbury?

Worth knowing

We have now removed Vale from standard checking as it is not playing nicely with mdformat

To do list

What needs to done still in this PR:

  • resolve prettier/mdformat differences @stichbury
  • fix FIXME points @stichbury
  • check through the actual built documentation @stichbury (note this can be done without manually looking through every page by generating the html and then doing a diff compared to the current version)
  • check Python code formatting @antonymilne

Follow up work

  • apply mdformat-ruff or mdformat-black or blacken-docs (preference is in that order), ideally with good line length @antonymilne. Needs to work for {.python} code blocks: easiest way is to do python {pycafe-link title="a"}. Tracked in Apply code formatting to code examples in our docs #719
  • work out why custom-components.md doesn't get formatted and un-ignore it @stichbury
  • Report issues to Vale about code within admonition blocks @stichbury

Notice

  • I acknowledge and agree that, by checking this box and clicking "Submit Pull Request":

    • I submit this contribution under the Apache 2.0 license and represent that I am entitled to do so on behalf of myself, my employer, or relevant third parties, as applicable.
    • I certify that (a) this contribution is my original creation and / or (b) to the extent it is not my original creation, I am authorized to submit this contribution on behalf of the original creator(s) or their licensees.
    • I certify that the use of this contribution as authorized by the Apache 2.0 license does not violate the intellectual property rights of anyone else.
    • I have not referenced individuals, products or companies in any commits, directly or indirectly.
    • I have not added data or restricted code in any commits, directly or indirectly.

Sorry, something went wrong.

@github-actions github-actions bot added the Vizro-AI 🤖 Issue/PR that addresses Vizro-AI package label Nov 14, 2024
for more information, see https://pre-commit.ci
Copy link
Contributor

github-actions bot commented Nov 14, 2024

View the example dashboards of the current commit live on PyCafe ☕ 🚀

Updated on: 2024-12-03 21:34:10 UTC
Commit: 64609ce

Link: vizro-core/examples/dev/

Link: vizro-core/examples/scratch_dev

Link: vizro-core/examples/visual-vocabulary/

Link: vizro-ai/examples/dashboard_ui/

README.md Outdated Show resolved Hide resolved
@antonymilne
Copy link
Contributor Author

Looks like we might need to disable prettier for md files if it conflicts with this. That's easy to do but let's see where mdformat and prettier disagree first.

…ormat

# Conflicts:
#	vizro-ai/docs/index.md
#	vizro-ai/docs/pages/user-guides/chart-examples.md
#	vizro-ai/docs/pages/user-guides/create-advanced-charts.md
#	vizro-ai/docs/pages/user-guides/create-complex-dashboard.md
#	vizro-ai/docs/pages/user-guides/retrieve-dashboard-code.md
#	vizro-core/changelog.d/20241030_170000_antony.milne_vvv_link_targets.md
#	vizro-core/changelog.d/20241105_170003_antony.milne_new_interaction.md
#	vizro-core/changelog.d/20241106_104745_antony.milne_dynamic_filter_2.md
#	vizro-core/changelog.d/20241106_134102_alexey_snigir_pytest_warning_ignore.md
#	vizro-core/changelog.d/20241112_120233_huong_li_nguyen_fix_404_page.md
#	vizro-core/docs/pages/explanation/authors.md
#	vizro-core/docs/pages/user-guides/card-button.md
#	vizro-core/examples/visual-vocabulary/README.md
vizro-ai/docs/index.md Outdated Show resolved Hide resolved
antonymilne and others added 2 commits November 29, 2024 09:40
for more information, see https://pre-commit.ci
vizro-core/CHANGELOG.md Outdated Show resolved Hide resolved
vizro-core/docs/index.md Outdated Show resolved Hide resolved
for more information, see https://pre-commit.ci
.pre-commit-config.yaml Outdated Show resolved Hide resolved
@antonymilne antonymilne changed the base branch from main to docs-changes December 3, 2024 15:14
@antonymilne antonymilne changed the base branch from docs-changes to main December 3, 2024 15:14
…o tidy/mdformat
Copy link
Contributor

@stichbury stichbury left a comment

Choose a reason for hiding this comment

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

Phew, thanks @antonymilne this was a huge one to coordinate. Docs look fine for core.

@huong-li-nguyen huong-li-nguyen self-requested a review December 3, 2024 16:29
petar-qb and others added 2 commits December 3, 2024 22:21
for more information, see https://pre-commit.ci
petar-qb and others added 2 commits December 3, 2024 22:32
for more information, see https://pre-commit.ci
Copy link
Contributor

@petar-qb petar-qb left a comment

Choose a reason for hiding this comment

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

Great initiative!! This tool cleans our docs really well 👍

@antonymilne antonymilne merged commit 5ec20d7 into main Dec 4, 2024
44 checks passed
@antonymilne antonymilne deleted the tidy/mdformat branch December 4, 2024 10:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Vizro-AI 🤖 Issue/PR that addresses Vizro-AI package
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants