Make documentation builds more reproducible by using virtualenv

.gitmodules

@@ -1,6 +0,0 @@
-[submodule "breathe"]
-	path = breathe
-	url = https://github.com/michaeljones/breathe.git
-[submodule "doc/sphinx-bootstrap-theme"]
-	path = doc/sphinx-bootstrap-theme
-	url = https://github.com/cppformat/sphinx-bootstrap-theme.git

breathe

@@ -1 +0,0 @@
-Subproject commit 33a6cce142119f8d1565513752b4bb4ace0ed85f

doc/CMakeLists.txt

@@ -1,18 +1,9 @@
-if (NOT EXISTS ${FORMAT_SOURCE_DIR}/breathe/breathe)
-  message(STATUS "Target 'doc' disabled (requires breathe module)")
+find_program(DOXYGEN doxygen)
+if (NOT DOXYGEN)
+  message(STATUS "Target 'doc' disabled (requires doxygen)")
   return ()
 endif ()
 
-foreach (program doxygen sphinx-build)
-  find_program(${program} ${program})
-  if (NOT ${program})
-    message(STATUS "Target 'doc' disabled (requires ${program})")
-    return ()
-  endif ()
-endforeach ()
+add_custom_target(doc COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/build.py)
 
-add_custom_target(doc
-  COMMAND ${doxygen}
-  COMMAND ${sphinx-build} -b html . html)
-
-install(DIRECTORY html/ DESTINATION share/doc/cppformat)
+install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html/ DESTINATION share/doc/cppformat)

doc/Doxyfile

@@ -1,20 +0,0 @@
-PROJECT_NAME     = C++ Format
-GENERATE_LATEX   = NO
-GENERATE_MAN     = NO
-GENERATE_RTF     = NO
-CASE_SENSE_NAMES = NO
-INPUT            = ../format.h
-QUIET            = YES
-JAVADOC_AUTOBRIEF = YES
-AUTOLINK_SUPPORT = NO
-GENERATE_HTML = NO
-GENERATE_XML = YES
-XML_OUTPUT   = doxyxml
-ALIASES = "rst=\verbatim embed:rst"
-ALIASES += "endrst=\endverbatim"
-PREDEFINED = _WIN32=1 \
-             FMT_NO_DEPRECATED=1 \
-             FMT_USE_VARIADIC_TEMPLATES=1 \
-             FMT_USE_RVALUE_REFERENCES=1
-EXCLUDE_SYMBOLS = fmt::internal::* BasicArg FormatParser StringValue \
-                  write_str

doc/build.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python
+# Build the documentation.
+
+from __future__ import print_function
+import os, shutil, tempfile
+from subprocess import check_call, Popen, PIPE
+
+def pip_install(package, commit=None):
+  "Install package using pip."
+  if commit:
+    package = 'git+git://github.com/{0}.git@{1}'.format(package, commit)
+  check_call(['pip', 'install', '-q', package])
+
+def build_docs(workdir, travis):
+  # Create virtualenv.
+  virtualenv_dir = os.path.join(workdir, 'virtualenv')
+  check_call(['virtualenv', virtualenv_dir])
+  activate_this_file = os.path.join(virtualenv_dir, 'bin', 'activate_this.py')
+  execfile(activate_this_file, dict(__file__=activate_this_file))
+  # Install Sphinx, Breathe and the Bootstrap theme.
+  pip_install('sphinx==1.2.2')
+  pip_install('michaeljones/breathe', '18bd461b4e29dde0adf5df4b3da7e5473e2c2983')
+  pip_install('cppformat/sphinx-bootstrap-theme', '534ba82ef51c17e0f13e8e57b9fa133fa1926c80')
+  # Build docs.
+  doc_dir = os.path.dirname(__file__)
+  p = Popen(['doxygen', '-'], stdin=PIPE)
+  p.communicate(input=r'''
+      PROJECT_NAME      = C++ Format
+      GENERATE_LATEX    = NO
+      GENERATE_MAN      = NO
+      GENERATE_RTF      = NO
+      CASE_SENSE_NAMES  = NO
+      INPUT             = {0}/format.h
+      QUIET             = YES
+      JAVADOC_AUTOBRIEF = YES
+      AUTOLINK_SUPPORT  = NO
+      GENERATE_HTML     = NO
+      GENERATE_XML      = YES
+      XML_OUTPUT        = doxyxml
+      ALIASES           = "rst=\verbatim embed:rst"
+      ALIASES          += "endrst=\endverbatim"
+      PREDEFINED        = _WIN32=1 \
+                          FMT_USE_VARIADIC_TEMPLATES=1 \
+                          FMT_USE_RVALUE_REFERENCES=1
+      EXCLUDE_SYMBOLS   = fmt::internal::* StringValue write_str
+    '''.format(os.path.dirname(doc_dir)))
+  if p.returncode != 0:
+    return p.returncode
+  check_call(['sphinx-build',
+              '-D', "breathe_projects.format=" + os.path.join(os.getcwd(), "doxyxml"),
+              '-b', 'html', doc_dir, 'html'])
+  return 0
+
+returncode = 1
+travis = 'TRAVIS' in os.environ
+workdir = tempfile.mkdtemp()
+try:
+  returncode = build_docs(workdir, travis=travis)
+finally:
+  # Don't remove workdir on Travis because the VM is discarded anyway.
+  if not travis:
+    shutil.rmtree(workdir)
+exit(returncode)

doc/conf.py

@@ -11,7 +11,7 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os, re, subprocess
+import sys, os, re, sphinx_bootstrap_theme, subprocess
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -21,7 +21,7 @@ import sys, os, re, subprocess
 # -- General configuration -----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
+needs_sphinx = '1.2'
 
 sys.path.append("../breathe")
 
@@ -32,7 +32,6 @@ if os.environ.get('READTHEDOCS', None) == 'True':
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.ifconfig', 'breathe']
 
-breathe_projects = { "format": "doxyxml" }
 breathe_default_project = "format"
 breathe_domain_by_extension = {"h" : "cpp"}
 
@@ -137,7 +136,7 @@ html_theme_options = {
 }
 
 # Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = ['sphinx-bootstrap-theme']
+html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".

doc/sphinx-bootstrap-theme

@@ -1 +0,0 @@
-Subproject commit c26c975e8af6a379f63f8bf969c015fa3b4a2d0a