Add a linter for docs/

[purva-thakre]

Previously discussed here: #2382 (comment)

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

mitiq/pyproject.toml

Lines 1 to 35 in bf82e84

	[tool.ruff]
	exclude = ["__init__.py"]
	line-length = 79
	[tool.ruff.lint]
	select = [
	# pycodestyle
	"E",
	# pyflakes
	"F",
	# isort
	"I",
	]
	[tool.pytest.ini_options]
	addopts = "--color=yes"
	filterwarnings = [
	# TODO: these are probably too restrictive
	'ignore::UserWarning',
	'ignore::DeprecationWarning',
	]
	[tool.mypy]
	exclude = 'mitiq.*.tests*'
	ignore_missing_imports = true
	# Enable a subset of strict options
	check_untyped_defs = true
	disallow_any_generics = true
	disallow_incomplete_defs = true
	disallow_subclassing_any = true
	disallow_untyped_defs = true
	no_implicit_optional = true
	warn_redundant_casts = true
	warn_unused_configs = true

[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.

[purva-thakre]

The drawback here is that this tool is not markdown specific.

Since most of our docs pages are in .md, adding a tool that is not specific to markdown seems redundant. I tried adding a trailing whitespace to check if the tool flagged the errors. It did not.

There are additional formatting issues with the .md files anyway. Some files have lines that run out of the page etc. markdownlint forces us to make changes to lines like this.

How about we don't add markdownlint as a dependency or as a check to the make format lines? We can use it as an editor extension. The drawback to this is that it is not a compatible extension for all editors.