search

OSGeo / gdal

GDAL is an open source MIT licensed translator library for raster and vector geospatial data formats.
https://gdal.org
Other
4.66k stars 2.46k forks source link

Add reStructuredText linting step to Azure Pipelines job #1576

Open mloskot opened 5 years ago

mloskot commented 5 years ago

This is TODO item to lint the *.rst files before building and deploying the docs.

mloskot commented 5 years ago

I've experimented with the famous https://github.com/twolfson/restructuredtext-lint/ but there seem to be issues with Sphinx directives and roles:

ERROR source/drivers/raster/pds.rst:29 Unknown directive type "supports_virtualio".
ERROR source/drivers/raster/pds.rst:103 Unknown interpreted text role "ref".

How to handle those needs to be investigated.

mloskot commented 5 years ago

I've experimented with https://github.com/myint/rstcheck too and it seems to have issues with Breathe directives

source/api/cpl.rst:10: (ERROR/3) Unknown directive type "doxygenfile".
source/api/gdaldataset_cpp.rst:7: (ERROR/3) Unknown directive type "doxygenclass".

Another interseting feature of rstcheck is validation of code blocks

source/tutorials/raster_api_tut.rst:34: (ERROR/3) (c) fatal error: gdal.h: No such file or directory
source/tutorials/raster_api_tut.rst:103: (ERROR/3) (c) error: unknown type name ‘GDALDriverH’

But the tool configurability seem to be a work (brainstorm) in progress https://github.com/myint/rstcheck/issues/31 Alternatively, cpp language can be ignored at single .rst file level https://github.com/myint/rstcheck#ignore-specific-languages (I have not found way to ignore it at .rstcheck.cfg config level).