From 8c24a423957c0b6d568998323d1f2c17c6a2a16e Mon Sep 17 00:00:00 2001 From: vitaut Date: Fri, 10 Apr 2015 08:39:09 -0700 Subject: [PATCH] Make documentation builds more reproducible by using virtualenv --- .gitmodules | 6 ---- breathe | 1 - doc/CMakeLists.txt | 19 +++--------- doc/Doxyfile | 20 ------------ doc/build.py | 63 ++++++++++++++++++++++++++++++++++++++ doc/conf.py | 7 ++--- doc/sphinx-bootstrap-theme | 1 - 7 files changed, 71 insertions(+), 46 deletions(-) delete mode 160000 breathe delete mode 100644 doc/Doxyfile create mode 100755 doc/build.py delete mode 160000 doc/sphinx-bootstrap-theme diff --git a/.gitmodules b/.gitmodules index a0b9aa8e..e69de29b 100644 --- a/.gitmodules +++ b/.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 diff --git a/breathe b/breathe deleted file mode 160000 index 33a6cce1..00000000 --- a/breathe +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 33a6cce142119f8d1565513752b4bb4ace0ed85f diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index fb2a8903..2990e8fc 100644 --- a/doc/CMakeLists.txt +++ b/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) diff --git a/doc/Doxyfile b/doc/Doxyfile deleted file mode 100644 index fcd6ad8f..00000000 --- a/doc/Doxyfile +++ /dev/null @@ -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 diff --git a/doc/build.py b/doc/build.py new file mode 100755 index 00000000..4b8354bb --- /dev/null +++ b/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) diff --git a/doc/conf.py b/doc/conf.py index cb2b4403..72a33e7b 100644 --- a/doc/conf.py +++ b/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 # " v documentation". diff --git a/doc/sphinx-bootstrap-theme b/doc/sphinx-bootstrap-theme deleted file mode 160000 index c26c975e..00000000 --- a/doc/sphinx-bootstrap-theme +++ /dev/null @@ -1 +0,0 @@ -Subproject commit c26c975e8af6a379f63f8bf969c015fa3b4a2d0a