[ovs-dev] build: Only re-gen HTML docs when needed.

Submitted by Russell Bryant on March 16, 2017, 5:01 p.m.

Details

Message ID 20170316170132.6486-1-russell@ovn.org
State Accepted
Headers show

Commit Message

Russell Bryant March 16, 2017, 5:01 p.m.
When sphinx-build is installed, the docs were being re-generated during
every invocation of "make".  This patch sets up dependencies such that
sphinx-build will only be executed if one of the documentation files has
changed.

Signed-off-by: Russell Bryant <russell@ovn.org>
---
 .gitignore                |  1 +
 Documentation/automake.mk | 11 ++++++-----
 2 files changed, 7 insertions(+), 5 deletions(-)

Comments

Ben Pfaff March 16, 2017, 8:57 p.m.
On Thu, Mar 16, 2017 at 01:01:32PM -0400, Russell Bryant wrote:
> When sphinx-build is installed, the docs were being re-generated during
> every invocation of "make".  This patch sets up dependencies such that
> sphinx-build will only be executed if one of the documentation files has
> changed.
> 
> Signed-off-by: Russell Bryant <russell@ovn.org>

I'd actually prefer to use a file with a regular name rather than a
dotfile (".htmldocs").  First, it's easier to spot a regular file when
I'm trying to figure out why something isn't rebuilding.  Second, we
have precedent with manpage-check and flake8-check.

Acked-by: Ben Pfaff <blp@ovn.org>
Ben Pfaff March 16, 2017, 8:58 p.m.
On Thu, Mar 16, 2017 at 01:57:20PM -0700, Ben Pfaff wrote:
> On Thu, Mar 16, 2017 at 01:01:32PM -0400, Russell Bryant wrote:
> > When sphinx-build is installed, the docs were being re-generated during
> > every invocation of "make".  This patch sets up dependencies such that
> > sphinx-build will only be executed if one of the documentation files has
> > changed.
> > 
> > Signed-off-by: Russell Bryant <russell@ovn.org>
> 
> I'd actually prefer to use a file with a regular name rather than a
> dotfile (".htmldocs").  First, it's easier to spot a regular file when
> I'm trying to figure out why something isn't rebuilding.  Second, we
> have precedent with manpage-check and flake8-check.
> 
> Acked-by: Ben Pfaff <blp@ovn.org>

Oh, and we should probably add the new target (under whatever name) to
CLEANFILES.
Russell Bryant March 20, 2017, 3:49 p.m.
On Thu, Mar 16, 2017 at 4:58 PM, Ben Pfaff <blp@ovn.org> wrote:
> On Thu, Mar 16, 2017 at 01:57:20PM -0700, Ben Pfaff wrote:
>> On Thu, Mar 16, 2017 at 01:01:32PM -0400, Russell Bryant wrote:
>> > When sphinx-build is installed, the docs were being re-generated during
>> > every invocation of "make".  This patch sets up dependencies such that
>> > sphinx-build will only be executed if one of the documentation files has
>> > changed.
>> >
>> > Signed-off-by: Russell Bryant <russell@ovn.org>
>>
>> I'd actually prefer to use a file with a regular name rather than a
>> dotfile (".htmldocs").  First, it's easier to spot a regular file when
>> I'm trying to figure out why something isn't rebuilding.  Second, we
>> have precedent with manpage-check and flake8-check.
>>
>> Acked-by: Ben Pfaff <blp@ovn.org>
>
> Oh, and we should probably add the new target (under whatever name) to
> CLEANFILES.

Thanks!  I made the requested changes and applied this to master.

Patch hide | download patch | download mbox

diff --git a/.gitignore b/.gitignore
index 4f50440..cd26dfe 100644
--- a/.gitignore
+++ b/.gitignore
@@ -30,6 +30,7 @@ 
 .libs
 .tmp_versions
 .gitattributes
+.htmldocs
 /Makefile
 /Makefile.in
 /aclocal.m4
diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index c4076aa..3872ad0 100644
--- a/Documentation/automake.mk
+++ b/Documentation/automake.mk
@@ -1,4 +1,4 @@ 
-EXTRA_DIST += \
+DOC_SOURCE = \
 	Documentation/group-selection-method-property.txt \
 	Documentation/_static/logo.png \
 	Documentation/_static/overview.png \
@@ -90,6 +90,8 @@  EXTRA_DIST += \
 	Documentation/internals/contributing/submitting-patches.rst \
 	Documentation/requirements.txt
 
+EXTRA_DIST += $(DOC_SOURCE)
+
 # You can set these variables from the command line.
 SPHINXOPTS =
 SPHINXBUILD = sphinx-build
@@ -106,9 +108,9 @@  sphinx_verbose_ = $(sphinx_verbose_@AM_DEFAULT_V@)
 sphinx_verbose_0 = -q
 
 if HAVE_SPHINX
-htmldocs:
-	$(AM_V_GEN)$(SPHINXBUILD) $(sphinx_verbose) -b html $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/html
-ALL_LOCAL += htmldocs
+.htmldocs: $(DOC_SOURCE)
+	$(AM_V_GEN)$(SPHINXBUILD) $(sphinx_verbose) -b html $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/html && touch $@
+ALL_LOCAL += .htmldocs
 
 check-docs:
 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/linkcheck
@@ -119,6 +121,5 @@  clean-docs:
 	rm -rf $(SPHINXBUILDDIR)/linkcheck
 CLEAN_LOCAL += clean-docs
 endif
-.PHONY: htmldocs
 .PHONY: check-docs
 .PHONY: clean-docs