[ovs-dev] [PATCH] doc: Correct type of highlighting

[Stephen Finucane]

On Fri, 2016-12-23 at 11:31 -0800, Ben Pfaff wrote:
> On Fri, Dec 23, 2016 at 06:50:41PM +0000, Stephen Finucane wrote:
> > On Fri, 2016-12-23 at 08:54 -0800, Ben Pfaff wrote:
> > > I've been toying with the idea that the build should break if
> > > there
> > > are
> > > any broken links (at least internal links) in the .rst files.  Is
> > > there
> > > a practical way to make that happen?
> > 
> > Any internal references (using the 'doc:' or 'ref:' roles) do raise
> > a
> > warnings if the link's broken. This will cause a broken local build
> > because warnings are treated as errors, but ReadTheDocs is less
> > stringent (presumably to ensure docs are available as much as
> > possible). I guess we could change this but it would only serve to
> > highlight issues once they've already been committed. A better
> > approach
> > would be to always build the docs locally before committing them to
> > highlight potential issues, but this is easily forgotten (as seen
> > in
> > this instance). Any ideas how we could automate this?
> 
> We have several targets that run on every plain "make" to check
> various
> correctness and style properties.  For example, take a look at the
> manpage-check and flake8-check targets in the top-level
> Makefile.am.  It
> would be nice to add a similar target that checked the documentation,
> at
> least in the case where the appropriate tools are installed.  Then
> any
> developer who runs "make" (and has the tools) would find the issue
> immediately, because the build would fail.

Gotcha. Did some rooting around and found a similar tool in Sphinx
(which gets cooler by the day). Just sent patches to implement this.
Let me know what you think.

Stephen