Merge pull request #498 from astrofrog/docs-parallel

Add a --parallel flag for build_docs

.travis.yml

@@ -12,7 +12,6 @@ sudo: false
 
 env:
   matrix:
-    - PYTHON_VERSION=3.5
     - PYTHON_VERSION=3.6
     - PYTHON_VERSION=3.7 SETUPTOOLS_VERSION=dev DEBUG=True
       CONDA_DEPENDENCIES="cython numpy pytest-cov sphinx-astropy'
@@ -26,38 +25,52 @@ env:
 
 matrix:
   include:
+
     # Do one build with sphinx-astropy as one of the tests bypasses the auto-
     # installation but we want to make sure that test runs for coverage.
     - os: linux
       env: PYTHON_VERSION=3.6 PIP_DEPENDENCIES='codecov'
     - os: linux
-      env: PYTHON_VERSION=3.6 SPHINX_VERSION='1.5' SETUPTOOLS_VERSION=30
-    - os: linux
-      env: PYTHON_VERSION=3.5 SPHINX_VERSION='1.5' SETUPTOOLS_VERSION=30
-           CONDA_DEPENDENCIES=`echo $CONDA_DEPENDENCIES 'numpydoc<0.9'`"
+      env: PYTHON_VERSION=3.6 SPHINX_VERSION='1.7' SETUPTOOLS_VERSION=30
     - os: linux
       env: PYTHON_VERSION=3.6 PIP_DEPENDENCIES='git+https://github.com/sphinx-doc/sphinx.git#egg=sphinx codecov'
            CONDA_DEPENDENCIES="setuptools cython numpy pytest-cov sphinx-astropy"
-           EVENT_TYPE='push pull_request cron'
+           EVENT_TYPE='push pull_request cron' CONDA_CHANNELS="astropy"
+
     # Test without installing numpy beforehand to make sure everything works
     # without assuming numpy is already installed
     - os: linux
       env: PYTHON_VERSION=3.6 CONDA_DEPENDENCIES='sphinx-astropy cython pytest-cov'
+           CONDA_CHANNELS="astropy"
+
+    # Windows builds - for now we need to install sphinx-astropy with pip since
+    # there is not a recent enough version of graphviz according to conda on Windows
+    - os: windows
+      env: PYTHON_VERSION=3.6
+           CONDA_DEPENDENCIES="setuptools cython numpy pytest-cov"
+           PIP_DEPENDENCIES="codecov sphinx-astropy"
+    - os: windows
+      env: PYTHON_VERSION=3.7
+           CONDA_DEPENDENCIES="setuptools cython numpy pytest-cov"
+           PIP_DEPENDENCIES="codecov sphinx-astropy"
 
     # Test conda's clang
     - os: osx
       env:
-        - PYTHON_VERSION=3.5
+        - PYTHON_VERSION=3.7
         - CONDA_DEPENDENCIES="setuptools sphinx-astropy cython numpy pytest-cov clang llvm-openmp matplotlib"
+        - CONDA_CHANNELS="astropy"
         - OPENMP_EXPECTED=True
         - CCOMPILER=clang
 
     # Test gcc on OSX
     - os: osx
       env:
-        - PYTHON_VERSION=3.5
+        - PYTHON_VERSION=3.6
         - CONDA_DEPENDENCIES="setuptools sphinx-astropy cython numpy pytest-cov gcc"
+        - CONDA_CHANNELS="astropy"
         - OPENMP_EXPECTED=True
+        - CONDA_CHANNELS="astropy conda-forge"
         - CCOMPILER=gcc
 
   # Uncomment the following if there are issues in setuptools that we

CHANGES.rst

@@ -4,7 +4,11 @@ astropy-helpers Changelog
 4.0 (unreleased)
 ------------------
 
-- No changes yet.
+- Changed minimum required Python version to 3.6. [#498]
+
+- Changed minimum required Sphinx version to 1.7. [#498]
+
+- Added a --parallel option for build_docs. [#498]
 
 
 3.2.2 (unreleased)

astropy_helpers/commands/build_sphinx.py

@@ -9,12 +9,8 @@
 
 from distutils import log
 
-from sphinx import __version__ as sphinx_version
 from sphinx.setup_command import BuildDoc as SphinxBuildDoc
 
-SPHINX_LT_16 = LooseVersion(sphinx_version) < LooseVersion('1.6')
-SPHINX_LT_17 = LooseVersion(sphinx_version) < LooseVersion('1.7')
-
 SUBPROCESS_TEMPLATE = """
 import os
 import sys
@@ -35,25 +31,17 @@
 def ensure_sphinx_astropy_installed():
     """
     Make sure that sphinx-astropy is available.
-
-    This returns the available version of sphinx-astropy as well as any
-    paths that should be added to sys.path for sphinx-astropy to be available.
     """
-    # We've split out the Sphinx part of astropy-helpers into sphinx-astropy
-    # but we want it to be auto-installed seamlessly for anyone using
-    # build_docs. We check if it's already installed, and if not, we install
-    # it to a local .eggs directory and add the eggs to the path (these
-    # have to each be added to the path, we can't add them by simply adding
-    # .eggs to the path)
-    sys_path_inserts = []
-    sphinx_astropy_version = None
+
     try:
         from sphinx_astropy import __version__ as sphinx_astropy_version  # noqa
     except ImportError:
-        raise ImportError("sphinx-astropy needs to be installed to build "
-                          "the documentation.")
+        sphinx_astropy_version = None
 
-    return sphinx_astropy_version, sys_path_inserts
+    if (sphinx_astropy_version is None
+            or LooseVersion(sphinx_astropy_version) < LooseVersion('1.2')):
+        raise ImportError("sphinx-astropy 1.2 or later needs to be installed to build "
+                            "the documentation.")
 
 
 class AstropyBuildDocs(SphinxBuildDoc):
@@ -83,6 +71,11 @@ class AstropyBuildDocs(SphinxBuildDoc):
         ('open-docs-in-browser', 'o',
          'Open the docs in a browser (using the webbrowser module) if the '
          'build finishes successfully.'))
+    user_options.append(
+        ('parallel=', 'j',
+         'Build the docs in parallel on the specified number of '
+         'processes. If "auto", all the cores on the machine will be '
+         'used.'))
 
     boolean_options = SphinxBuildDoc.boolean_options[:]
     boolean_options.append('warnings-returncode')
@@ -99,6 +92,7 @@ def initialize_options(self):
         self.open_docs_in_browser = False
         self.warnings_returncode = False
         self.traceback = False
+        self.parallel = None
 
     def finalize_options(self):
 
@@ -149,15 +143,12 @@ def run(self):
         else:
             ah_path = os.path.abspath(ah_importer.path)
 
-        if SPHINX_LT_17:
-            build_main = 'from sphinx import build_main'
-        else:
-            build_main = 'from sphinx.cmd.build import build_main'
+        build_main = 'from sphinx.cmd.build import build_main'
 
         # We need to make sure sphinx-astropy is installed
-        sphinx_astropy_version, extra_paths = ensure_sphinx_astropy_installed()
+        ensure_sphinx_astropy_installed()
 
-        sys_path_inserts = [build_cmd_path, ah_path] + extra_paths
+        sys_path_inserts = [build_cmd_path, ah_path]
         sys_path_inserts = os.linesep.join(['sys.path.insert(0, {0!r})'.format(path) for path in sys_path_inserts])
 
         argv = []
@@ -166,14 +157,7 @@ def run(self):
             argv.append('-W')
 
         if self.no_intersphinx:
-            # Note, if sphinx_astropy_version is None, this could indicate an
-            # old version of setuptools, but sphinx-astropy is likely ok, so
-            # we can proceed.
-            if sphinx_astropy_version is None or LooseVersion(sphinx_astropy_version) >= LooseVersion('1.1'):
-                argv.extend(['-D', 'disable_intersphinx=1'])
-            else:
-                log.warn('The -n option to disable intersphinx requires '
-                         'sphinx-astropy>=1.1. Ignoring.')
+            argv.extend(['-D', 'disable_intersphinx=1'])
 
         # We now need to adjust the flags based on the parent class's options
 
@@ -198,20 +182,20 @@ def run(self):
         elif self.verbose > 1:
             argv.append('-v')
 
-        if SPHINX_LT_17:
-            argv.insert(0, 'sphinx-build')
+        if self.parallel is not None:
+            argv.append(f'-j={self.parallel}')
 
         if isinstance(self.builder, str):
             builders = [self.builder]
         else:
             builders = self.builder
 
         subproccode = SUBPROCESS_TEMPLATE.format(build_main=build_main,
-                                             srcdir=self.source_dir,
-                                             sys_path_inserts=sys_path_inserts,
-                                             builders=builders,
-                                             argv=argv,
-                                             output_dir=os.path.abspath(self.build_dir))
+                                                 srcdir=self.source_dir,
+                                                 sys_path_inserts=sys_path_inserts,
+                                                 builders=builders,
+                                                 argv=argv,
+                                                 output_dir=os.path.abspath(self.build_dir))
 
         log.debug('Starting subprocess of {0} with python code:\n{1}\n'
                   '[CODE END])'.format(sys.executable, subproccode))

astropy_helpers/tests/test_setup_helpers.py

@@ -246,7 +246,7 @@ def test_missing_cython_c_files(capsys, pyx_extension_test_package,
         assert msg in stderr
 
 
-@pytest.mark.parametrize('mode', ['cli', 'cli-w', 'cli-sphinx', 'cli-l'])
+@pytest.mark.parametrize('mode', ['cli', 'cli-w', 'cli-sphinx', 'cli-l', 'cli-parallel'])
 def test_build_docs(capsys, tmpdir, mode):
     """
     Test for build_docs
@@ -309,6 +309,8 @@ class B(A):
             run_setup('setup.py', ['build_docs', '-l'])
         elif mode == 'cli-sphinx':
             run_setup('setup.py', ['build_sphinx'])
+        elif mode == 'cli-parallel':
+            run_setup('setup.py', ['build_docs', '--parallel=2'])
 
     assert os.path.exists(docs_dir.join('_build', 'html', 'index.html').strpath)
 

setup.cfg

@@ -23,7 +23,7 @@ classifiers =
 
 [options]
 zip_safe = False
-python_requires = >=3.5
+python_requires = >=3.6
 packages = find:
 
 [options.package_data]