Docstring/PEP 257 fixes for the docs_builder app (#2832)

Author: alexwlchan

readthedocs/doc_builder/backends/mkdocs.py

@@ -17,9 +17,8 @@
 
 class BaseMkdocs(BaseBuilder):
 
-    """
-    Mkdocs builder
-    """
+    """Mkdocs builder"""
+
     use_theme = True
 
     def __init__(self, *args, **kwargs):
@@ -30,10 +29,7 @@ def __init__(self, *args, **kwargs):
         self.root_path = self.version.project.checkout_path(self.version.slug)
 
     def append_conf(self, **kwargs):
-        """
-        Set mkdocs config values
-        """
-
+        """Set mkdocs config values"""
         # Pull mkdocs config data
         try:
             user_config = yaml.safe_load(

readthedocs/doc_builder/backends/sphinx.py

@@ -24,9 +24,7 @@
 
 class BaseSphinx(BaseBuilder):
 
-    """
-    The parent for most sphinx builders.
-    """
+    """The parent for most sphinx builders."""
 
     def __init__(self, *args, **kwargs):
         super(BaseSphinx, self).__init__(*args, **kwargs)
@@ -39,9 +37,7 @@ def __init__(self, *args, **kwargs):
             self.old_artifact_path = os.path.join(docs_dir, self.sphinx_build_dir)
 
     def _write_config(self, master_doc='index'):
-        """
-        Create ``conf.py`` if it doesn't exist.
-        """
+        """Create ``conf.py`` if it doesn't exist."""
         docs_dir = self.docs_dir()
         conf_template = render_to_string('sphinx/conf.py.conf',
                                          {'project': self.project,
@@ -53,9 +49,7 @@ def _write_config(self, master_doc='index'):
         safe_write(conf_file, conf_template)
 
     def append_conf(self, **kwargs):
-        """Modify the given ``conf.py`` file from a whitelisted user's project.
-        """
-
+        """Modify given ``conf.py`` file from a whitelisted user's project."""
         # Pull config data
         try:
             conf_py_path = self.version.get_conf_py_path()
@@ -242,7 +236,7 @@ def move(self, **kwargs):
 
 class LatexBuildCommand(BuildCommand):
 
-    '''Ignore LaTeX exit code if there was file output'''
+    """Ignore LaTeX exit code if there was file output"""
 
     def run(self):
         super(LatexBuildCommand, self).run()
@@ -254,7 +248,7 @@ def run(self):
 
 class DockerLatexBuildCommand(DockerBuildCommand):
 
-    '''Ignore LaTeX exit code if there was file output'''
+    """Ignore LaTeX exit code if there was file output"""
 
     def run(self):
         super(DockerLatexBuildCommand, self).run()

readthedocs/doc_builder/base.py

@@ -19,6 +19,7 @@ def decorator(*args, **kw):
 
 
 class BaseBuilder(object):
+
     """
     The Base for all Builders. Defines the API for subclasses.
 
@@ -41,21 +42,18 @@ def __init__(self, build_env, python_env, force=False):
         )
 
     def force(self, **kwargs):
-        """
-        An optional step to force a build even when nothing has changed.
-        """
+        """An optional step to force a build even when nothing has changed."""
         log.info("Forcing a build")
         self._force = True
 
     def build(self, id=None, **kwargs):
-        """
-        Do the actual building of the documentation.
-        """
+        """Do the actual building of the documentation."""
         raise NotImplementedError
 
     def move(self, **kwargs):
         """
-        Move the documentation from it's generated place to its artifact directory.
+        Move the documentation from where it was generated to
+        its artifact directory.
         """
         if os.path.exists(self.old_artifact_path):
             if os.path.exists(self.target):
@@ -66,17 +64,13 @@ def move(self, **kwargs):
             log.warning("Not moving docs, because the build dir is unknown.")
 
     def clean(self, **kwargs):
-        """
-        Clean the path where documentation will be built
-        """
+        """Clean the path where documentation will be built"""
         if os.path.exists(self.old_artifact_path):
             shutil.rmtree(self.old_artifact_path)
             log.info("Removing old artifact path: %s" % self.old_artifact_path)
 
     def docs_dir(self, docs_dir=None, **kwargs):
-        """
-        Handle creating a custom docs_dir if it doesn't exist.
-        """
+        """Handle creating a custom docs_dir if it doesn't exist."""
         checkout_path = self.project.checkout_path(self.version.slug)
         if not docs_dir:
             for doc_dir_name in ['docs', 'doc', 'Doc', 'book']:
@@ -89,10 +83,7 @@ def docs_dir(self, docs_dir=None, **kwargs):
         return docs_dir
 
     def create_index(self, extension='md', **kwargs):
-        """
-        Create an index file if it needs it.
-        """
-
+        """Create an index file if it needs it."""
         docs_dir = self.docs_dir()
 
         index_filename = os.path.join(docs_dir, 'index.{ext}'.format(ext=extension))
@@ -119,5 +110,5 @@ def create_index(self, extension='md', **kwargs):
         return 'index'
 
     def run(self, *args, **kwargs):
-        '''Proxy run to build environment'''
+        """Proxy run to build environment"""
         return self.build_env.run(*args, **kwargs)

readthedocs/doc_builder/config.py

@@ -126,7 +126,6 @@ def load_yaml_config(version):
     This uses the configuration logic from `readthedocs-build`,
     which will keep parsing consistent between projects.
     """
-
     checkout_path = version.project.checkout_path(version.slug)
     env_config = {}
 

readthedocs/doc_builder/constants.py

@@ -1,4 +1,4 @@
-'''Doc build constants'''
+"""Doc build constants"""
 
 import os
 import re

readthedocs/doc_builder/environments.py

@@ -1,6 +1,4 @@
-'''
-Documentation Builder Environments
-'''
+"""Documentation Builder Environments"""
 
 import os
 import re
@@ -38,7 +36,7 @@
 
 class BuildCommand(BuildCommandResultMixin):
 
-    '''Wrap command execution for execution in build environments
+    """Wrap command execution for execution in build environments
 
     This wraps subprocess commands with some logic to handle exceptions,
     logging, and setting up the env for the build command.
@@ -57,7 +55,7 @@ class BuildCommand(BuildCommandResultMixin):
     :param build_env: build environment to use to execute commands
     :param bin_path: binary path to add to PATH resolution
     :param description: a more grokable description of the command being run
-    '''
+    """
 
     def __init__(self, command, cwd=None, shell=False, environment=None,
                  combine_output=True, input_data=None, build_env=None,
@@ -94,12 +92,12 @@ def __str__(self):
         return '\n'.join([self.get_command(), output])
 
     def run(self):
-        '''Set up subprocess and execute command
+        """Set up subprocess and execute command
 
         :param cmd_input: input to pass to command in STDIN
         :type cmd_input: str
         :param combine_output: combine STDERR into STDOUT
-        '''
+        """
         log.info("Running: '%s' [%s]", self.get_command(), self.cwd)
 
         self.start_time = datetime.utcnow()
@@ -159,14 +157,14 @@ def run(self):
             self.end_time = datetime.utcnow()
 
     def get_command(self):
-        '''Flatten command'''
+        """Flatten command"""
         if hasattr(self.command, '__iter__') and not isinstance(self.command, str):
             return ' '.join(self.command)
         else:
             return self.command
 
     def save(self):
-        '''Save this command and result via the API'''
+        """Save this command and result via the API"""
         data = {
             'build': self.build_env.build.get('id'),
             'command': self.get_command(),
@@ -181,18 +179,18 @@ def save(self):
 
 class DockerBuildCommand(BuildCommand):
 
-    '''Create a docker container and run a command inside the container
+    """Create a docker container and run a command inside the container
 
     Build command to execute in docker container
-    '''
+    """
 
     def run(self):
-        '''Execute command in existing Docker container
+        """Execute command in existing Docker container
 
         :param cmd_input: input to pass to command in STDIN
         :type cmd_input: str
         :param combine_output: combine STDERR into STDOUT
-        '''
+        """
         log.info("Running in container %s: '%s' [%s]",
                  self.build_env.container_id, self.get_command(), self.cwd)
 
@@ -310,16 +308,16 @@ def handle_exception(self, exc_type, exc_value, _):
             return True
 
     def run(self, *cmd, **kwargs):
-        '''Shortcut to run command from environment'''
+        """Shortcut to run command from environment"""
         return self.run_command_class(cls=self.command_class, cmd=cmd, **kwargs)
 
     def run_command_class(self, cls, cmd, **kwargs):
-        '''Run command from this environment
+        """Run command from this environment
 
         Use ``cls`` to instantiate a command
 
         :param warn_only: Don't raise an exception on command failure
-        '''
+        """
         warn_only = kwargs.pop('warn_only', False)
         # Remove PATH from env, and set it to bin_path if it isn't passed in
         env_path = self.environment.pop('BIN_PATH', None)
@@ -353,21 +351,21 @@ def run_command_class(self, cls, cmd, **kwargs):
 
     @property
     def successful(self):
-        '''Is build completed, without top level failures or failing commands'''
+        """Is build completed, without top level failures or failing commands"""
         return (self.done and self.failure is None and
                 all(cmd.successful for cmd in self.commands))
 
     @property
     def failed(self):
-        '''Is build completed, but has top level failure or failing commands'''
+        """Is build completed, but has top level failure or failing commands"""
         return (self.done and (
             self.failure is not None or
             any(cmd.failed for cmd in self.commands)
         ))
 
     @property
     def done(self):
-        '''Is build in finished state'''
+        """Is build in finished state"""
         return (self.build is not None and
                 self.build['state'] == BUILD_STATE_FINISHED)
 
@@ -429,13 +427,14 @@ def update_build(self, state=None):
 
 class LocalEnvironment(BuildEnvironment):
 
-    '''Local execution environment'''
+    """Local execution environment"""
+
     command_class = BuildCommand
 
 
 class DockerEnvironment(BuildEnvironment):
 
-    '''
+    """
     Docker build environment, uses docker to contain builds
 
     If :py:data:`settings.DOCKER_ENABLE` is true, build documentation inside a
@@ -447,7 +446,8 @@ class DockerEnvironment(BuildEnvironment):
     data.
 
     :param docker_socket: Override to Docker socket URI
-    '''
+    """
+
     command_class = DockerBuildCommand
     container_image = DOCKER_IMAGE
     container_mem_limit = DOCKER_LIMITS.get('memory')
@@ -471,7 +471,7 @@ def __init__(self, *args, **kwargs):
             self.container_time_limit = self.project.container_time_limit
 
     def __enter__(self):
-        '''Start of environment context'''
+        """Start of environment context"""
         log.info('Creating container')
         try:
             # Test for existing container. We remove any stale containers that
@@ -511,7 +511,7 @@ def __enter__(self):
         return self
 
     def __exit__(self, exc_type, exc_value, tb):
-        '''End of environment context'''
+        """End of environment context"""
         ret = self.handle_exception(exc_type, exc_value, tb)
 
         # Update buildenv state given any container error states first
@@ -541,7 +541,7 @@ def __exit__(self, exc_type, exc_value, tb):
         return ret
 
     def get_client(self):
-        '''Create Docker client connection'''
+        """Create Docker client connection"""
         try:
             if self.client is None:
                 self.client = Client(
@@ -561,14 +561,14 @@ def get_client(self):
 
     @property
     def container_id(self):
-        '''Return id of container if it is valid'''
+        """Return id of container if it is valid"""
         if self.container_name:
             return self.container_name
         elif self.container:
             return self.container.get('Id')
 
     def container_state(self):
-        '''Get container state'''
+        """Get container state"""
         client = self.get_client()
         try:
             info = client.inspect_container(self.container_id)
@@ -577,13 +577,13 @@ def container_state(self):
             return None
 
     def update_build_from_container_state(self):
-        '''Update buildenv state from container state
+        """Update buildenv state from container state
 
         In the case of the parent command exiting before the exec commands
         finish and the container is destroyed, or in the case of OOM on the
         container, set a failure state and error message explaining the failure
         on the buildenv.
-        '''
+        """
         state = self.container_state()
         if state is not None and state.get('Running') is False:
             if state.get('ExitCode') == DOCKER_TIMEOUT_EXIT_CODE:
@@ -598,7 +598,7 @@ def update_build_from_container_state(self):
                      .format(state.get('Error'))))
 
     def create_container(self):
-        '''Create docker container'''
+        """Create docker container"""
         client = self.get_client()
         image = self.container_image
         if self.project.container_image: