[Bug]: Labeling math equations breaks parsing

larsoner commented 1 year ago

To Dos

[X] I tested with the latest released version.
[X] I have checked the issues and think that this is not a duplicate.
[X] I added a very descriptive title to this issue.

Example Code (rst)

.. math:: V(\boldsymbol{r_i}) = c_0 + \sum_{j=1}^{N}c_{i}g_{m}(cos(\boldsymbol{r_i}, \boldsymbol{r_{j}}))
   :label: model

Relevant log output

doc/_includes/channel_interpolation.rst:24: (ERROR/3) Error in "math" directive:

Description

The :label: causes the Error. Removing it makes the check pass, but then the equation label is gone.

Operating System

macOS

Operating System Details

No response

Python Version

3.11.5

rstcheck Version

6.2.0, 1.1.1

Additional Context

No response

Cielquan commented 1 year ago

I took a look and the issue has 2 sides:

The error message is only half complete. unknown option: "label" is missing after the colon. rstcheck under the hood gives the rst source to docutils and then processes the error messages coming back from doctuils. So rstcheck itself does no rst source validation. Because all errors come back in one big string rstcheck splits the error string by lines and then parses each line. When the line begins with the file name take it else discard it. Source The error message in this case has line breaks and the original message looks like this:
```
doc/_includes/channel_interpolation.rst:24: (ERROR/3) Error in "math" directive:
unknown option: "label".
```

.. math:: V(\boldsymbol{r_i}) = c0 + \sum{j=1}^{N}c{i}g{m}(cos(\boldsymbol{ri}, \boldsymbol{r{j}})) :label: model



2. The `:label:` role is unknown.
According to the official docutils docs the `.. math::` directive has no `:label:` role: [link](https://www.docutils.org/docs/ref/rst/directives.html#math).
And in the sphinx docs I also could not find the `:label:` role for the `.. math::` directive [link](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-math).
Only the base docutils and sphinx directives and roles are known in the check process. So when the `:label:` role come from e.g. a sphinx plugin it unfortunately does not work. Currently the only option is to add the role to the ignore list via `ignore_roles` in your config file.

If you have a good solution to this problem, which also considers other cases, I am open for ideas and contributions.

EDIT: Related to #4

larsoner commented 1 year ago

Weird that :label: even worked (I just checked that it does) but :name: seems more standard and also works so I'll just fix my RST!

rstcheck / rstcheck-core