Add Markdown documentation linting

[msteslov]

Fixes #1785.

Adds a Markdown linting job to the basic CI workflow using rumdl.

Testing:

• rumdl check --config .rumdl.toml --respect-gitignore --exclude 'build,**/build' .
• actionlint -shellcheck "" .github/workflows/basic.yml

• Does this PR change the input/output behaviour of a cryptographic algorithm (i.e., does it change known answer test values)? (If so, a version bump will be required from x.y.z to x.(y+1).0.)
• Does this PR change the list of algorithms available -- either adding, removing, or renaming? Does this PR otherwise change an API? (If so, PRs in fully supported downstream projects dependent on these, i.e., oqs-provider will also need to be ready for review and merge by the time this is merged. Also, make sure to update the list of algorithms in the continuous benchmarking files: .github/workflows/kem-bench.yml and sig-bench.yml)

AI assistance was used for repository inspection and drafting; I reviewed and verified the final changes.

[xuganyu96]

LGTM. Thank you for the contribution.

[coveralls]

coverage: 81.418% (-0.004%) from 81.422% — msteslov:add-markdown-linter into open-quantum-safe:main

[xuganyu96]

I am sorry to have to walk back on my previous approval. The code change makes sense to me, but the choice of tool could use some justification. I did a quick search and found other markdown linters written in Ruby (markdownlint), Python (pymarkdown), and Rust (rumdl), and many others. It feels a tiny bit uncomfortable to introduce NPM into dev dependencies. I intuitively prefer keeping dev dependencies either in the Python ecosystem or as small binaries. Of course if markdownlint-cli is indeed a much more mature project than the other choices, then I am okay with introducing it into liboqs.

[msteslov]

Updated the PR to avoid the NPM dependency: it now uses rumdl==0.2.4 installed via Python/PyPI in CI, with a narrow .rumdl.toml rule set that passes on the existing documentation without unrelated Markdown churn. I also reduced the PR scope to only the workflow and linter configuration files.

[xuganyu96]

Thank you for the contribution. LGTM pending the GitHub Actions results.

[xuganyu96]

Hi, sorry for the late review and for walking back my approval again. It would great if you can address GitHub security bot's suggestions. Here is a script you can run to get the hashes.

wget https://files.pythonhosted.org/packages/c6/aa/d49dffee785b9004107042085d17fa010f455306817f033c0990b4abd3bc/rumdl-0.2.18-py3-none-win_amd64.whl
wget https://files.pythonhosted.org/packages/25/9d/25b76cd9fad8c8b070b97a21f01562911663cf7b4ed9238acaccfe61dd80/rumdl-0.2.18-py3-none-musllinux_1_2_x86_64.whl
wget https://files.pythonhosted.org/packages/51/6c/7ade7138bca98ab306554c5d9e6e6f135c839fe14dcb79809d8dd7eb8eaa/rumdl-0.2.18-py3-none-musllinux_1_2_aarch64.whl
wget https://files.pythonhosted.org/packages/1d/23/86a1cb7c274b41f09fe5e921ee8317d355a575b7476b577284c5ed33ee63/rumdl-0.2.18-py3-none-manylinux_2_28_x86_64.whl
wget https://files.pythonhosted.org/packages/05/9d/21697889a192fa8c0b5ad4832f43a5a94699fb5da8f81ce7a72cec60b893/rumdl-0.2.18-py3-none-manylinux_2_28_aarch64.whl
wget https://files.pythonhosted.org/packages/ae/59/ab5be3d6494c55ca2d2beda516f8fb69e5db84e3cf5d114fcdbd78593389/rumdl-0.2.18-py3-none-macosx_11_0_arm64.whl
wget https://files.pythonhosted.org/packages/8f/0f/35d32954432cbe7bbfd5613e9eca6f41cb6d05373d81efd662e690ab2ed2/rumdl-0.2.18-py3-none-macosx_10_12_x86_64.whl

pip hash *.whl

[xuganyu96]

Pinging @open-quantum-safe/liboqs-committers for inputs on setting up markdown linter as a pre-commit hook. Check .githooks/ and CONTRIBUTING.md for details.

edit: this could be a useful entrypoint from which we can later add more auto-formatters and linters, then move some of the style checks off CI/CD.

[dstebila]

Pinging @open-quantum-safe/liboqs-committers for inputs on setting up markdown linter as a pre-commit hook. Check .githooks/ and CONTRIBUTING.md for details.

edit: this could be a useful entrypoint from which we can later add more auto-formatters and linters, then move some of the style checks off CI/CD.

I don't have any experience with pre-commit hooks. What would contributors have to do differently in their setup and workflow?

[xuganyu96]

I don't have any experience with pre-commit hooks. What would contributors have to do differently in their setup and workflow?

Contributors need to configure git to set the hooks directory (see CONTRIBUTING.md). They will also need to install the markdown linter rumdl. The pre-commit script will prompt the user to use pip, though the user can choose to procure its own copy (such as from cargo).

The pre-commit script will run at every commit but before the commit is "committed". If the script exits with non-zero code, then the commit will fail, and the contributor will need to fix whatever the pre-commit script reports.

[dstebila]

I don't have any experience with pre-commit hooks. What would contributors have to do differently in their setup and workflow?

Contributors need to configure git to set the hooks directory (see CONTRIBUTING.md). They will also need to install the markdown linter rumdl. The pre-commit script will prompt the user to use pip, though the user can choose to procure its own copy (such as from cargo).

The pre-commit script will run at every commit but before the commit is "committed". If the script exits with non-zero code, then the commit will fail, and the contributor will need to fix whatever the pre-commit script reports.

If a contributor doesn't activate the git hooks, will the commit go through?

[xuganyu96]

If a contributor doesn't activate the git hooks, will the commit go through?

Yes, and even if the git hooks were configured, they can be bypassed with git commit --no-verify. We will need a separate test at CI pipeline.

[xuganyu96]

@baentsch Could you take another look at this pull request? I've added a pre-commit hook that automatically runs the markdown linter. Thank you.