Looking for a Rst Validator

[anurag garg]

Hi Sphinx users,

Is there a rst validator that I can use to validate the rst files before running sphinx?

I am having issues in building docs after updating Sphinx current version (from: 1.8.3) which errors out with an issue in a rst file without mentioning which file has the issue.

Thanks!

[Sandra McCann]

We've been using rstcheck for Ansible docs and it helps. I can't say it detects everything that Sphinx might find problematic, but it does find a lot.
https://pypi.org/project/rstcheck/

Sandra McCann

[Stefano David]

There's a rst-lint in pypi [1], but I never tried it.

About the error(s) you receive, even if they don't give you the exact file where the issue takes place, they tell you what kind of problem you should investigate. Perhaps if you copy them here someone might help you further.

Cheers,
Stefano

[1] https://pypi.org/project/restructuredtext-lint/ 

[anurag garg]

Hi Sandra, Stefano

Thanks for info. I tried the rstcheck but it had mostly Info and Warnings, so I think it should be fine for Sphinx.

So for the error, generally Sphinx has following warnings/info:-

File-name.rst:2: WARNING: duplicate label rulesummary, other instance in File-name.rst

But the case where our docs fails is :-

reST markup error:
:16: (SEVERE/4) Unexpected section title.

},

Thanks,

Anurag

[Stefano David]

On Thursday, 26 August 2021 at 16:52:36 UTC+2 anurag garg wrote:

Hi Sandra, Stefano

Thanks for info. I tried the rstcheck but it had mostly Info and Warnings, so I think it should be fine for Sphinx.

So for the error, generally Sphinx has following warnings/info:-

File-name.rst:2: WARNING: duplicate label rulesummary, other instance in File-name.rst

You probaly have included a file (fileA.rst) in another one (fileB.rst). you need to add fileA.rst to the exclude_patterns configuration option of conf.py

But the case where our docs fails is :-

reST markup error:
:16: (SEVERE/4) Unexpected section title.

You need to make sure that the headings always follow the same pattern, you can not have for example a third level of heading follow a first level.

HTH,

Stefano

[anurag garg]

Hi Stefano,

Thanks for the hint. I will take a look into this :)

One thing I noticed is that we use ~~~~~ for defining the headings in some manually written docs which is allowed by rST but isn't mentioned by Sphinx. This worked in older version of Sphinx not sure if newer versions break this. Will try and replace these with another symbol.

Thanks,

Anurag