Merge pull request readthedocs#1945 from rtfd/yaml-format-support

Add support for `formats` in the YAML config.

Author: ericholscher

docs/yaml-config.rst

@@ -12,6 +12,35 @@ must be in the root directory of your project.
 Supported Settings
 ------------------
 
+formats
+~~~~~~~
+
+* Default: `['htmlzip', 'pdf', 'epub']`
+* Options: htmlzip, pdf, epub
+
+The formats of your documentation you want to be built.
+
+.. note:: We will always build an HTML & JSON version of your documentation.
+		  These are used for web serving & search indexing, respectively.
+
+.. code-block:: yaml
+
+	requirements_file: requirements/docs.txt
+
+requirements_file
+~~~~~~~~~~~~~~~~~
+
+* Default: `None`
+* Type: Path (specified from the root of the project)
+
+The path to your Pip requirements file.
+
+.. code-block:: yaml
+
+	requirements_file: requirements/docs.txt
+
+
+
 conda
 ~~~~~
 
@@ -64,19 +93,6 @@ When true, install your project into the Virtualenv when building documentation.
 	python:
 	   setup_py_install: true
 
-requirements_file
-~~~~~~~~~~~~~~~~~
-
-* Default: `None`
-* Type: Path (specified from the root of the project)
-
-The path to your Pip requirements file.
-
-.. code-block:: yaml
-
-	requirements_file: requirements/docs.txt
-
-
 .. To implement..
 
 	type

readthedocs/doc_builder/config.py

@@ -80,6 +80,18 @@ def requirements_file(self):
         else:
             return self._project.requirements_file
 
+    @property
+    def formats(self):
+        if 'formats' in self._yaml_config:
+            return self._yaml_config['formats']
+        else:
+            formats = ['htmlzip']
+            if self._project.enable_epub_build:
+                formats += ['epub']
+            if self._project.enable_pdf_build:
+                formats += ['pdf']
+            return formats
+
     # Not implemented until we figure out how to keep in sync with the webs.
     # Probably needs to be version-specific as well, not project.
     # @property

readthedocs/projects/tasks.py

@@ -74,7 +74,8 @@ class UpdateDocsTask(Task):
     default_retry_delay = (7 * 60)
     name = 'update_docs'
 
-    def __init__(self, build_env=None, python_env=None, force=False, search=True, localmedia=True,
+    def __init__(self, build_env=None, python_env=None, config=None,
+                 force=False, search=True, localmedia=True,
                  build=None, project=None, version=None):
         self.build_env = build_env
         self.python_env = python_env
@@ -90,6 +91,8 @@ def __init__(self, build_env=None, python_env=None, force=False, search=True, lo
         self.project = {}
         if project is not None:
             self.project = project
+        if config is not None:
+            self.config = config
 
     def _log(self, msg):
         log.info(LOG_TEMPLATE
@@ -349,24 +352,27 @@ def build_docs_search(self):
 
     def build_docs_localmedia(self):
         """Get local media files with separate build"""
+        if 'htmlzip' not in self.config.formats:
+            return False
+
         if self.build_localmedia:
             if self.project.is_type_sphinx:
                 return self.build_docs_class('sphinx_singlehtmllocalmedia')
         return False
 
     def build_docs_pdf(self):
         """Build PDF docs"""
-        if (self.project.slug in HTML_ONLY or
-                not self.project.is_type_sphinx or
-                not self.project.enable_pdf_build):
+        if ('pdf' not in self.config.formats or
+            self.project.slug in HTML_ONLY or
+                not self.project.is_type_sphinx):
             return False
         return self.build_docs_class('sphinx_pdf')
 
     def build_docs_epub(self):
         """Build ePub docs"""
-        if (self.project.slug in HTML_ONLY or
-                not self.project.is_type_sphinx or
-                not self.project.enable_epub_build):
+        if ('epub' not in self.config.formats or
+            self.project.slug in HTML_ONLY or
+                not self.project.is_type_sphinx):
             return False
         return self.build_docs_class('sphinx_epub')
 

readthedocs/rtd_tests/tests/test_builds.py

@@ -5,10 +5,12 @@
 import mock
 
 from readthedocs.projects.models import Project
+from readthedocs.doc_builder.config import ConfigWrapper
 from readthedocs.doc_builder.environments import LocalEnvironment
 from readthedocs.doc_builder.python_environments import Virtualenv
 from readthedocs.doc_builder.loader import get_builder_class
 from readthedocs.projects.tasks import UpdateDocsTask
+from readthedocs.rtd_tests.tests.test_config_wrapper import get_build_config
 
 from ..mocks.environment import EnvironmentMockGroup
 
@@ -38,8 +40,10 @@ def test_build(self):
 
         build_env = LocalEnvironment(project=project, version=version, build={})
         python_env = Virtualenv(version=version, build_env=build_env)
-        task = UpdateDocsTask(build_env=build_env, python_env=python_env, version=version,
-                              project=project, search=False, localmedia=False)
+        yaml_config = get_build_config({})
+        config = ConfigWrapper(version=version, yaml_config=yaml_config)
+        task = UpdateDocsTask(build_env=build_env, project=project, python_env=python_env,
+                              version=version, search=False, localmedia=False, config=config)
         task.build_docs()
 
         # Get command and check first part of command list is a call to sphinx
@@ -61,8 +65,11 @@ def test_build_respects_pdf_flag(self):
 
         build_env = LocalEnvironment(project=project, version=version, build={})
         python_env = Virtualenv(version=version, build_env=build_env)
-        task = UpdateDocsTask(build_env=build_env, python_env=python_env, version=version,
-                              project=project, search=False, localmedia=False)
+        yaml_config = get_build_config({})
+        config = ConfigWrapper(version=version, yaml_config=yaml_config)
+        task = UpdateDocsTask(build_env=build_env, project=project, python_env=python_env,
+                              version=version, search=False, localmedia=False, config=config)
+
         task.build_docs()
 
         # The HTML and the Epub format were built.
@@ -84,8 +91,35 @@ def test_build_respects_epub_flag(self):
 
         build_env = LocalEnvironment(project=project, version=version, build={})
         python_env = Virtualenv(version=version, build_env=build_env)
-        task = UpdateDocsTask(build_env=build_env, python_env=python_env, version=version,
-                              project=project, search=False, localmedia=False)
+        yaml_config = get_build_config({})
+        config = ConfigWrapper(version=version, yaml_config=yaml_config)
+        task = UpdateDocsTask(build_env=build_env, project=project, python_env=python_env,
+                              version=version, search=False, localmedia=False, config=config)
+        task.build_docs()
+
+        # The HTML and the Epub format were built.
+        self.mocks.html_build.assert_called_once_with()
+        self.mocks.epub_build.assert_called_once_with()
+        # PDF however was disabled and therefore not built.
+        self.assertFalse(self.mocks.pdf_build.called)
+
+    def test_build_respects_yaml(self):
+        '''Test YAML build options'''
+        project = get(Project,
+                      slug='project-1',
+                      documentation_type='sphinx',
+                      conf_py_file='test_conf.py',
+                      enable_pdf_build=False,
+                      enable_epub_build=False,
+                      versions=[fixture()])
+        version = project.versions.all()[0]
+
+        build_env = LocalEnvironment(project=project, version=version, build={})
+        python_env = Virtualenv(version=version, build_env=build_env)
+        yaml_config = get_build_config({'formats': ['epub']})
+        config = ConfigWrapper(version=version, yaml_config=yaml_config)
+        task = UpdateDocsTask(build_env=build_env, project=project, python_env=python_env,
+                              version=version, search=False, localmedia=False, config=config)
         task.build_docs()
 
         # The HTML and the Epub format were built.
@@ -137,8 +171,10 @@ def test_build_pdf_latex_failures(self):
 
         build_env = LocalEnvironment(project=project, version=version, build={})
         python_env = Virtualenv(version=version, build_env=build_env)
+        yaml_config = get_build_config({})
+        config = ConfigWrapper(version=version, yaml_config=yaml_config)
         task = UpdateDocsTask(build_env=build_env, project=project, python_env=python_env,
-                              version=version, search=False, localmedia=False)
+                              version=version, search=False, localmedia=False, config=config)
 
         # Mock out the separate calls to Popen using an iterable side_effect
         returns = [
@@ -177,8 +213,10 @@ def test_build_pdf_latex_not_failure(self):
 
         build_env = LocalEnvironment(project=project, version=version, build={})
         python_env = Virtualenv(version=version, build_env=build_env)
+        yaml_config = get_build_config({})
+        config = ConfigWrapper(version=version, yaml_config=yaml_config)
         task = UpdateDocsTask(build_env=build_env, project=project, python_env=python_env,
-                              version=version, search=False, localmedia=False)
+                              version=version, search=False, localmedia=False, config=config)
 
         # Mock out the separate calls to Popen using an iterable side_effect
         returns = [

requirements/pip.txt

@@ -1,11 +1,11 @@
-## Upgraded packages
+# Base packages
 pip==7.1.0
 virtualenv==13.1.0
 docutils==0.11
 Sphinx==1.3.4
 Pygments==2.0.2
 mkdocs==0.14.0
-
+readthedocs-build==2.0.2
 django==1.8.3
 
 git+https://github.com/django-tastypie/django-tastypie.git@1e1aff3dd4dcd21669e9c68bd7681253b286b856#egg=django-tastypie
@@ -72,4 +72,3 @@ nilsimsa==0.3.7
 git+https://github.com/alex/django-filter.git#egg=django-filter
 git+https://github.com/ericflo/django-pagination.git@e5f669036c#egg=django_pagination-dev
 git+https://github.com/alex/django-taggit.git#egg=django_taggit-dev
-git+https://github.com/rtfd/readthedocs-build.git@a751769#egg=readthedocs_build