Install [docs] dependencies in setup.py

Remove the pip install command from the docs Makefile used for installing the sphinx distribution.
Add the distribution to the extras in setup.py so that it can be installed if required by the user.
Add condition in the conf.py file to check if the [docs] dependencies are installed. If not, suitable error is displayed.

fixes buildbot#3435

.travis.yml

@@ -132,7 +132,7 @@ install:
   # Install sphinx so that pylint will be able to import it
   - "[ $TESTS != lint ] || pip install sphinx==1.3.3"
   # TODO: Pin Sphinx version to workaround http://trac.buildbot.net/ticket/3408
-  - "[ $TESTS != docs ] || pip install sphinx==1.3.3"
+  - "[ $TESTS != docs ] || pip install -e ./master[docs]"
 
 before_script:
   # create real MySQL database for tests

circle.yml

@@ -8,7 +8,7 @@ machine:
 dependencies:
   override:
     - pyenv global 2.7.11
-    - pip install -e pkg -e master -e slave -e worker
+    - pip install -e pkg -e master[docs] -e slave -e worker
 
 test:
   override:

master/docs/Makefile

@@ -1,6 +1,6 @@
 all: docs.tgz
 
-.PHONY: tutorial manual pipdeps
+.PHONY: tutorial manual
 
 VERSION := $(shell if [ -n "$$VERSION" ]; then echo $$VERSION; else PYTHONPATH=..:$${PYTHONPATH} python -c 'from buildbot import version; print version'; fi)
 
@@ -10,8 +10,6 @@ TAR_TRANSFORM := $(if $(filter bsdtar,$(TAR_VERSION)),-s /^html/$(VERSION)/,--tr
 docs.tgz: clean html singlehtml
 	sed -e 's!href="index.html#!href="#!g' < _build/singlehtml/index.html > _build/html/full.html
 	tar -C _build $(TAR_TRANSFORM) -zcf $@ html
-pipdeps:
-	pip install sphinxcontrib-blockdiag 'docutils>=0.8'
 
 # -- Makefile for Sphinx documentation --
 
@@ -50,38 +48,38 @@ help:
 clean:
 	-rm -rf $(BUILDDIR)/*
 
-html: conf.py pipdeps
+html: conf.py
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
-dirhtml: conf.py pipdeps
+dirhtml: conf.py
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
 
-singlehtml: conf.py pipdeps
+singlehtml: conf.py
 	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
 	@echo
 	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
 
-pickle: conf.py pipdeps
+pickle: conf.py
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files."
 
-json: conf.py pipdeps
+json: conf.py
 	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
 	@echo
 	@echo "Build finished; now you can process the JSON files."
 
-htmlhelp: conf.py pipdeps
+htmlhelp: conf.py
 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in $(BUILDDIR)/htmlhelp."
 
-qthelp: conf.py pipdeps
+qthelp: conf.py
 	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
@@ -90,7 +88,7 @@ qthelp: conf.py pipdeps
 	@echo "To view the help file:"
 	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/BuildbotTutorial.qhc"
 
-devhelp: conf.py pipdeps
+devhelp: conf.py
 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
 	@echo
 	@echo "Build finished."
@@ -99,46 +97,46 @@ devhelp: conf.py pipdeps
 	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/BuildbotTutorial"
 	@echo "# devhelp"
 
-epub: conf.py pipdeps
+epub: conf.py
 	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
 	@echo
 	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
 
-latex: conf.py pipdeps
+latex: conf.py
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
 	@echo "Run \`make' in that directory to run these through (pdf)latex" \
 	      "(use \`make latexpdf' here to do that automatically)."
 
-latexpdf: conf.py pipdeps
+latexpdf: conf.py
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through pdflatex..."
 	make -C $(BUILDDIR)/latex all-pdf
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
-text: conf.py pipdeps
+text: conf.py
 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
 	@echo
 	@echo "Build finished. The text files are in $(BUILDDIR)/text."
 
-man: conf.py pipdeps
+man: conf.py
 	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
 	@echo
 	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
 
-changes: conf.py pipdeps
+changes: conf.py
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
 	@echo
 	@echo "The overview file is in $(BUILDDIR)/changes."
 
-linkcheck: conf.py pipdeps
+linkcheck: conf.py
 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in $(BUILDDIR)/linkcheck/output.txt."
 
-doctest: conf.py pipdeps
+doctest: conf.py
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/doctest/output.txt."

master/docs/conf.py

@@ -21,7 +21,18 @@
 sys.path.append(os.path.abspath('.'))
 
 # -- General configuration -----------------------------------------------------
-
+try:
+    import sphinxcontrib.blockdiag
+except ImportError:
+    raise RuntimeError("sphinxcontrib.blockdiag is not installed. "
+        "Please install documentation dependencies with `pip install buildbot[docs]`")
+
+import pkg_resources
+try:
+    pkg_resources.require('docutils>=0.8')
+except pkg_resources.ResolutionError:
+    raise RuntimeError("docutils is not installed or has incompatible version. "
+        "Please install documentation dependencies with `pip install buildbot[docs]`")
 # If your documentation needs a minimal Sphinx version, state it here.
 needs_sphinx = '1.0'
 

master/setup.py

@@ -429,6 +429,11 @@ def define_plugin_entries(groups):
         'tls': [
             'Twisted[tls] ' + twisted_ver,
         ],
+        'docs': [
+            'sphinx==1.3.3',
+            'sphinxcontrib-blockdiag',
+            'docutils>=0.8',
+        ],
     }
 
     if os.getenv('NO_INSTALL_REQS'):

rtd-requirements.txt

@@ -4,7 +4,4 @@
 -e master/
 
 # Install docs dependencies.
-# When issue 3435 will be resolved, instead of these lines
-# `[docs]` extras should be added to master installation.
-sphinxcontrib-blockdiag
-docutils>=0.8
+-e master[docs]