EbookFoundation
/
readthedocs.org
mirror of https://github.com/EbookFoundation/readthedocs.org.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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

tox-dependencies
Alex Chan 2017-05-10 22:41:35 +01:00 committed by Anthony
parent a66bd56bad
commit 587f5ee99d
6 changed files with 48 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
readthedocs/doc_builder/backends/mkdocs.py
View File

@ -17,9 +17,8 @@ OVERRIDE_TEMPLATE_DIR = '%s/readthedocs/templates/mkdocs/overrides' % settings.S
class BaseMkdocs(BaseBuilder):
"""
Mkdocs builder
"""
"""Mkdocs builder"""
use_theme = True
def __init__(self, *args, **kwargs):
@ -30,10 +29,7 @@ class BaseMkdocs(BaseBuilder):
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(

16
readthedocs/doc_builder/backends/sphinx.py
View File

@ -24,9 +24,7 @@ log = logging.getLogger(__name__)
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 @@ class BaseSphinx(BaseBuilder):
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 @@ class BaseSphinx(BaseBuilder):
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 @@ class EpubBuilder(BaseSphinx):
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 @@ class LatexBuildCommand(BuildCommand):
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()

27
readthedocs/doc_builder/base.py
View File

@ -19,6 +19,7 @@ def restoring_chdir(fn):
class BaseBuilder(object):
"""
The Base for all Builders. Defines the API for subclasses.
@ -41,21 +42,18 @@ class BaseBuilder(object):
)
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 @@ class BaseBuilder(object):
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 @@ class BaseBuilder(object):
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 @@ If you want to use another markup, choose a different builder in your settings.
return 'index'
def run(self, *args, **kwargs):
'''Proxy run to build environment'''
"""Proxy run to build environment"""
return self.build_env.run(*args, **kwargs)

1
readthedocs/doc_builder/config.py
View File

@ -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 = {}

2
readthedocs/doc_builder/constants.py
View File

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

60
readthedocs/doc_builder/environments.py
View File

@ -1,6 +1,4 @@
'''
Documentation Builder Environments
'''
"""Documentation Builder Environments"""
import os
import re
@ -38,7 +36,7 @@ log = logging.getLogger(__name__)
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 @@ class BuildCommand(BuildCommandResultMixin):
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 @@ class BuildCommand(BuildCommandResultMixin):
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 @@ class BuildCommand(BuildCommandResultMixin):
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 @@ class BuildEnvironment(object):
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,13 +351,13 @@ class BuildEnvironment(object):
@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)
@ -367,7 +365,7 @@ class BuildEnvironment(object):
@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 @@ class BuildEnvironment(object):
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 @@ class DockerEnvironment(BuildEnvironment):
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 @@ class DockerEnvironment(BuildEnvironment):
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 @@ class DockerEnvironment(BuildEnvironment):
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 @@ class DockerEnvironment(BuildEnvironment):
@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 @@ class DockerEnvironment(BuildEnvironment):
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 @@ class DockerEnvironment(BuildEnvironment):
.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: