Add a linter for `docs/`

[purva-thakre]

Previously discussed here: https://github.com/unitaryfund/mitiq/pull/2382#discussion_r1633795704

Option 1: There exists a Sphinx extension for .rst files. Will require additional configuration as most of our examples and user guides are written in .md format

Option 2: markdownlint for .md files has a nice set of pre-defined rules. We can also define our own rules as needed.

Option 3: https://github.com/jackdewinter/pymarkdown

[purva-thakre]

@natestemen What are your preferences?

I prefer Option 2 over the other two. The main caveat for this is that it is not available as a PyPI package. We can use it in Github Actions or as a VS Code extension.

[purva-thakre]

Added a draft PR for this.

We need to agree on which rules we want to keep and which ones we want to ignore. The installation workflow for the cli is a little bit convoluted as I cannot use pip to install markdownlint-cli.

Locally, almost all the failures are due to violation of default line-length in the .md files in docs/ after markdownlint -f docs/ is used to fix the easily fixable errors.

markdownlint_all.txt markdownlint_minus_fixable_errors.txt

I did not want to commit the changes related to the easily fixable errors as we have not agreed on the ruleset yet.

But once we agree on the rules, we can use the toml file to ignore/follow a set of rules.

https://github.com/DavidAnson/markdownlint/blob/b2305efafb034b1f328845aec9928b5363ffd646/schema/.markdownlint.yaml

https://github.com/unitaryfund/mitiq/blob/bf82e84410e1805437e15f1d26b0c5be8e8dcb8a/pyproject.toml#L1-L35

[jordandsullivan]

@purva-thakre can you add the new commit with the above edits? Let's try to figure out which issues this is actually fixing (i.e. formatting issues that would have been very obtrusive otherwise).

As well as deciding on rules.

[natestemen]

I left this comment over on Purva's PR, but it more likely belongs here:

I don't love the idea of adding node as a dependency to Mitiq. A simpler tool that can get us part of the way there is https://editorconfig.org/, and it's supported by almost all editors. Setting trim_trailing_whitespace to true would fix some of these issues. The drawback here is that this tool is not markdown specific.