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

Ben Pfaff blp at ovn.org
Fri Dec 23 19:31:14 UTC 2016


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.


More information about the dev mailing list