doc: Add Markdown lint section to coding-style.rst

This commit is contained in:
Eduardo Almeida
2024-10-18 13:58:03 +01:00
parent 203d6330d6
commit ad1a8e9f86

View File

@@ -1820,3 +1820,77 @@ add the following configuration to ``.vscode/settings.json``:
"pyproject.toml",
],
}
Markdown Lint
*************
.. _Markdownlint: https://github.com/markdownlint/markdownlint
.. _Markdownlint Rules: https://github.com/markdownlint/markdownlint/blob/main/docs/RULES.md
.. _Markdownlint Configuration Style File: https://github.com/markdownlint/markdownlint/blob/main/docs/creating_styles.md
.. _Markdownlint Docker Hub: https://hub.docker.com/r/markdownlint/markdownlint
.. _Markdownlint Docker Instructions: https://github.com/markdownlint/markdownlint/tree/main/tools/docker
.. _Markdownlint VS Code Extension: https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint
|ns3| uses `Markdownlint`_ as a linter of Markdown files.
This linter checks if Markdown files follow a set of defined rules, in order to encourage
standardization and consistency of Markdown files across parsers.
It also ensures that Markdown files are correctly interpreted and rendered.
Markdownlint detects linting issues, but it can not fix them automatically.
The issues must be fixed manually.
Markdownlint configuration
==========================
Markdownlint's settings are saved in the file ``.mdl_style.rb``.
This file is defined in `Markdownlint Configuration Style File`_, which explains how to
customize the tool to enable / disable rules or customize its parameters.
The list of Markdown rules supported by Markdownlint is available in `Markdownlint Rules`_.
Install and Run Markdownlint
============================
Markdownlint is written in Ruby. To run Markdownlint, either use the official
Markdownlint Docker image or install Ruby and Markdownlint.
Run Markdownlint with Docker image
##################################
Markdownlint has an official Docker image in `Markdownlint Docker Hub`_ with the tool
and all dependencies installed.
The instructions to use the Docker image are available in `Markdownlint Docker Instructions`_.
To run Markdownlint in a Docker container, use the following command:
.. sourcecode:: console
docker run -v .:/data markdownlint/markdownlint -s .mdl_style.rb .
Install and Run Markdownlint with Ruby
######################################
To install Markdownlint natively, you need to have Ruby installed in your system.
Check the installation instructions in the Ruby's official documentation.
After installing Ruby in your system, install Markdownlint using the following command:
.. sourcecode:: console
gem install mdl
To run Markdownlint and check Markdown files for linting issues, run Markdownlint
using the following command:
.. sourcecode:: console
mdl -s .mdl_style.rb .
VS Code Extension
=================
For VS Code users, the `Markdownlint VS Code Extension`_ extension is available in the marketplace.
This extension is inspired in `Markdownlint`_ and follows the same set of rules.
The Markdownlint extension automatically analyzes files open in the editor and provides inline hints
when issues are detected. It can automatically fix most issues related with formatting.