search

open-quantum-safe / liboqs

C library for prototyping and experimenting with quantum-resistant cryptography
https://openquantumsafe.org/
Other
1.68k stars 414 forks source link

Add documentation Markdown linter to CI #1785

Open baentsch opened 1 month ago

baentsch commented 1 month ago

As per original suggestion by @beldmit (https://github.com/open-quantum-safe/liboqs/pull/1784#issuecomment-2097810424).

praveksharma commented 1 month ago

I suggest we use a maintained tool (such as markdownlint; including this as an example not suggesting we use specifically this tool) instead of maintaining our own script.

Since a linter would target specific markdown spec(s) I suggest we also choose which spec we want out markdown files to conform to (in addition to GH flavoured markdown). This may also ease future discussion/resolution for doc generation issues.

baentsch commented 1 month ago

I suggest we use a maintained tool

Fully agree. Instead of starting a discussion on a spec and as we're really only talking about GH documents, what about "just" using the GHdocs linter setup?

planetf1 commented 1 month ago

I'd agree with @baentsch that if the target is github markdown then using the github-supported configuration makes sense.

I use markdownlint (defaults, in vscode) myself as a first-pass checker.