| Message ID | 20161223230412.24118-2-stephen@that.guru |
|---|---|
| State | Changes Requested |
| Headers | show |
On Fri, Dec 23, 2016 at 11:04:12PM +0000, Stephen Finucane wrote: > This does basic validation of the syntax and validates all external > links. > > The nitpick ('-n') flag is added to ensure all possible warnings are > raised. > > Signed-off-by: Stephen Finucane <stephen@that.guru> > Cc: Ben Pfaff <blp@ovn.org> This does seem pretty fantastic, but it's really slow and requires network access. It'd be nice for running occasionally (or to add to the travis build), but I don't think we should run it on every build. Also, it complain https://msdn.microsoft.com/en-us/library/windows/desktop/aa366510(v=vs.85).aspx I was envisioning something that just checked internal links. I think that, if I change linkcheck to html, this comes pretty close to that. On my machine, that takes 4.2 seconds from a clean build, which is slow for running on every build, but it takes less than .3 seconds the second time with no changes, which I think would be acceptable. Also, I think that we can probably make reruns even faster than .3 seconds if we make docs-check a real target by making it depend on the files that generate the documentation, so that docs only get rebuilt if any of their sources changed. Something like this: ALL_LOCAL += docs-check docs-check: $(EXTRA_DIST) $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) -q $(SPHINXBUILDDIR)/html touch $@ and, you know, at that point really we don't have a check anymore, we have actual HTML docs that always get nicely generated whenever we run "make", which is pretty nice, so that we might as well just: ALL_LOCAL += htmldocs htmldocs: $(EXTRA_DIST) $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/html touch $@ Right? Well, except that $(EXTRA_DIST) is obviously not the right dependency, presumably there should be a better variable. (And of course we'd want to wrap the whole thing in "if HAVE_SPHINX", once we have that.)
diff --git a/Documentation/automake.mk b/Documentation/automake.mk index 98adca7..b27ad13 100644 --- a/Documentation/automake.mk +++ b/Documentation/automake.mk @@ -96,9 +96,14 @@ SPHINXBUILDDIR = $(builddir)/Documentation/_build # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -W -d $(SPHINXBUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SPHINXSRCDIR) +ALLSPHINXOPTS = -W -n -d $(SPHINXBUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SPHINXSRCDIR) .PHONY: htmldocs htmldocs: rm -rf $(SPHINXBUILDDIR)/* $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/html + +.PHONY: docs-check +ALL_LOCAL += docs-check +docs-check: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) -q $(SPHINXBUILDDIR)/linkcheck diff --git a/Documentation/conf.py b/Documentation/conf.py index 63f5877..06f50bc 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -113,6 +113,8 @@ pygments_style = 'sphinx' # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False +# If true, check the validity of #anchors in links. +linkcheck_anchors = False # -- Options for HTML output ----------------------------------------------
This does basic validation of the syntax and validates all external links. The nitpick ('-n') flag is added to ensure all possible warnings are raised. Signed-off-by: Stephen Finucane <stephen@that.guru> Cc: Ben Pfaff <blp@ovn.org> --- Documentation/automake.mk | 7 ++++++- Documentation/conf.py | 2 ++ 2 files changed, 8 insertions(+), 1 deletion(-)