ci: use markdownlint to enforce mkdocs compatibility (backport #14114)

mergify[bot] commented 2 weeks ago

mkdocs uses a markdown renderer that is hardcoded to 4 spaces per tab for detecting indentation levels, including ordered- and unordered-lists. Since we cannot easily change the renderer, begin using a markdown linter in CI that will fail if official docs do not adhere to the spacing rules.

As a starting point, the markdownlint config does not begin with the default set of checks, which might overwhelm attempts to fix them. Instead, focus on list-tab-spacing rules and a few other highly useful checks.

markdownlint also has some gaps in its abilities that allow common Rook doc issues to pass acceptance. However, it allows creating custom linting plugins. Create 2 such linting plugins to check 2 things:

all doc lines (except code blocks) must be aligned to a 4-space boundary, without exception. This ensures that markdown will render correctly with mkdocs. This unfortunately makes it possible to create lists that are internally aligned strangely.
admonitions must all follow the same format of
```
!!! header
  body
```

For the strange lists, this is allowed and renders correctly, but it looks strange:

- first bullet
- second bullet
    still second bullet
- third bullet

    has a paragraph
    of text inside

- last bullet

Checklist:

[ ] Commit Message Formatting: Commit titles and messages follow guidelines in the developer guide.
[ ] Reviewed the developer guide on Submitting a Pull Request
[ ] Pending release notes updated with breaking and/or notable changes for the next minor release.
[ ] Documentation has been updated, if necessary.
[ ] Unit tests have been added, if necessary.
[ ] Integration tests have been added, if necessary.
This is an automatic backport of pull request #14114 done by Mergify.

mergify[bot] commented 2 weeks ago

Cherry-pick of c9d99e01a08871788a10307882c35dbc640f6858 has failed:

On branch mergify/bp/release-1.14/pr-14114
Your branch is up to date with 'origin/release-1.14'.

You are currently cherry-picking commit c9d99e01a.
  (fix conflicts and run "git cherry-pick --continue")
  (use "git cherry-pick --skip" to skip this patch)
  (use "git cherry-pick --abort" to cancel the cherry-pick operation)

Changes to be committed:
    new file:   .markdownlint-cli2.cjs
    modified:   .vscode/settings.json
    modified:   Documentation/CRDs/Block-Storage/ceph-block-pool-crd.md
    modified:   Documentation/CRDs/Cluster/ceph-cluster-crd.md
    modified:   Documentation/CRDs/Cluster/external-cluster/topology-for-external-mode.md
    modified:   Documentation/CRDs/Cluster/network-providers.md
    modified:   Documentation/CRDs/Cluster/pvc-cluster.md
    modified:   Documentation/CRDs/Cluster/stretch-cluster.md
    modified:   Documentation/CRDs/Object-Storage/ceph-object-store-crd.md
    modified:   Documentation/CRDs/Object-Storage/ceph-object-store-user-crd.md
    modified:   Documentation/CRDs/Object-Storage/ceph-object-zone-crd.md
    modified:   Documentation/CRDs/Shared-Filesystem/ceph-filesystem-crd.md
    modified:   Documentation/CRDs/ceph-client-crd.md
    modified:   Documentation/CRDs/ceph-nfs-crd.md
    modified:   Documentation/Contributing/development-environment.md
    modified:   Documentation/Contributing/development-flow.md
    modified:   Documentation/Contributing/documentation.md
    modified:   Documentation/Contributing/rook-test-framework.md
    modified:   Documentation/Getting-Started/Prerequisites/authenticated-registry.md
    modified:   Documentation/Getting-Started/example-configurations.md
    modified:   Documentation/Getting-Started/quickstart.md
    modified:   Documentation/Storage-Configuration/Advanced/ceph-configuration.md
    modified:   Documentation/Storage-Configuration/Advanced/ceph-mon-health.md
    modified:   Documentation/Storage-Configuration/Advanced/configuration.md
    modified:   Documentation/Storage-Configuration/Advanced/key-management-system.md
    modified:   Documentation/Storage-Configuration/Block-Storage-RBD/rbd-async-disaster-recovery-failover-failback.md
    modified:   Documentation/Storage-Configuration/Block-Storage-RBD/rbd-mirroring.md
    modified:   Documentation/Storage-Configuration/Ceph-CSI/ceph-csi-drivers.md
    modified:   Documentation/Storage-Configuration/Ceph-CSI/ceph-csi-snapshot.md
    modified:   Documentation/Storage-Configuration/Monitoring/ceph-dashboard.md
    modified:   Documentation/Storage-Configuration/Monitoring/ceph-monitoring.md
    modified:   Documentation/Storage-Configuration/NFS/nfs-csi-driver.md
    modified:   Documentation/Storage-Configuration/NFS/nfs-security.md
    modified:   Documentation/Storage-Configuration/Object-Storage-RGW/ceph-object-bucket-claim.md
    modified:   Documentation/Storage-Configuration/Object-Storage-RGW/ceph-object-bucket-notifications.md
    modified:   Documentation/Storage-Configuration/Object-Storage-RGW/ceph-object-multisite.md
    modified:   Documentation/Storage-Configuration/Object-Storage-RGW/cosi.md
    modified:   Documentation/Storage-Configuration/Shared-Filesystem-CephFS/filesystem-mirroring.md
    modified:   Documentation/Storage-Configuration/Shared-Filesystem-CephFS/filesystem-storage.md
    modified:   Documentation/Storage-Configuration/ceph-teardown.md
    modified:   Documentation/Troubleshooting/ceph-common-issues.md
    modified:   Documentation/Troubleshooting/ceph-csi-common-issues.md
    modified:   Documentation/Troubleshooting/common-issues.md
    modified:   Documentation/Troubleshooting/disaster-recovery.md
    modified:   Documentation/Troubleshooting/kubectl-plugin.md
    modified:   Documentation/Troubleshooting/openshift-common-issues.md
    modified:   Documentation/Troubleshooting/performance-profiling.md
    modified:   Documentation/Upgrade/ceph-upgrade.md
    modified:   Documentation/Upgrade/health-verification.md
    modified:   Documentation/Upgrade/rook-upgrade.md
    modified:   README.md
    new file:   tests/scripts/markdownlint-admonitions.js
    new file:   tests/scripts/markdownlint-tab-spacing.js

Unmerged paths:
  (use "git add <file>..." to mark resolution)
    both modified:   Documentation/CRDs/Cluster/external-cluster/external-cluster.md
    both modified:   Documentation/Storage-Configuration/Ceph-CSI/ceph-csi-volume-clone.md

To fix up this pull request, you can check it out locally. See documentation: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/checking-out-pull-requests-locally

BlaineEXE commented 2 weeks ago

@mergifyio rebase

mergify[bot] commented 2 weeks ago

rebase

☑️ Nothing to do

- [ ] `-conflict` [📌 rebase requirement] - [X] `-closed` [📌 rebase requirement] - [X] `queue-position=-1` [📌 rebase requirement] - [X] any of: - [X] `#commits-behind>0` [📌 rebase requirement] - [ ] `#commits>1` [📌 rebase requirement] - [ ] `-linear-history` [📌 rebase requirement]

mergify[bot] commented 2 weeks ago

This pull request has merge conflicts that must be resolved before it can be merged. @mergify[bot] please rebase it. https://rook.io/docs/rook/latest/Contributing/development-flow/#updating-your-fork

BlaineEXE commented 2 weeks ago

@mergify rebase

mergify[bot] commented 2 weeks ago

rebase

☑️ Nothing to do

- [ ] `-conflict` [📌 rebase requirement] - [X] `-closed` [📌 rebase requirement] - [X] `queue-position=-1` [📌 rebase requirement] - [X] any of: - [X] `#commits-behind>0` [📌 rebase requirement] - [ ] `#commits>1` [📌 rebase requirement] - [ ] `-linear-history` [📌 rebase requirement]

BlaineEXE commented 2 weeks ago

I still don't understand @mergify rebase. It seems utterly useless for actually rebasing, so I did it manually after backporting the 2 recent doc PRs. No conflicts at all after that.

travisn commented 2 weeks ago

I still don't understand @mergify rebase. It seems utterly useless for actually rebasing, so I did it manually after backporting the 2 recent doc PRs. No conflicts at all after that.

I've also found mergify rebase doesn't seems to work when there are conflicts

rook / rook

ci: use markdownlint to enforce mkdocs compatibility (backport #14114) #14146

☑️ Nothing to do

☑️ Nothing to do