From 0fcbe841e490641ac829a3d9d59e07c003045ce3 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Mon, 25 Dec 2017 19:12:06 -0500 Subject: [PATCH 1/5] Better message on auto generated index file Closes #3351 --- readthedocs/doc_builder/base.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/readthedocs/doc_builder/base.py b/readthedocs/doc_builder/base.py index c5051dc0f3f..ad83cbfc0b1 100644 --- a/readthedocs/doc_builder/base.py +++ b/readthedocs/doc_builder/base.py @@ -101,7 +101,8 @@ def create_index(self, extension='md', **__): This is an autogenerated index file. -Please create a ``{dir}/index.{ext}`` or ``{dir}/README.{ext}`` file with your own content. +Please create a ``index.{ext}`` or ``README.{ext}`` file with your own content +under the root directory in your repository (or under ``/docs`` directory). If you want to use another markup, choose a different builder in your settings. """ From 835371e0c3ad12e923ae14ec0c678165ab7e682e Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Mon, 25 Dec 2017 19:15:25 -0500 Subject: [PATCH 2/5] Add pre-commit suggestions --- readthedocs/doc_builder/base.py | 39 +++++++++++++++++++-------------- 1 file changed, 22 insertions(+), 17 deletions(-) diff --git a/readthedocs/doc_builder/base.py b/readthedocs/doc_builder/base.py index ad83cbfc0b1..e341e5ac600 100644 --- a/readthedocs/doc_builder/base.py +++ b/readthedocs/doc_builder/base.py @@ -1,11 +1,14 @@ +# -*- coding: utf-8 -*- """Base classes for Builders.""" -from __future__ import absolute_import -from builtins import object -from functools import wraps -import os +from __future__ import ( + absolute_import, division, print_function, unicode_literals) + import logging +import os import shutil +from builtins import object +from functools import wraps log = logging.getLogger(__name__) @@ -19,6 +22,7 @@ def decorator(*args, **kw): return fn(*args, **kw) finally: os.chdir(path) + return decorator @@ -27,11 +31,12 @@ class BaseBuilder(object): """ The Base for all Builders. Defines the API for subclasses. - Expects subclasses to define ``old_artifact_path``, - which points at the directory where artifacts should be copied from. + Expects subclasses to define ``old_artifact_path``, which points at the + directory where artifacts should be copied from. """ _force = False + # old_artifact_path = .. def __init__(self, build_env, python_env, force=False): @@ -41,13 +46,11 @@ def __init__(self, build_env, python_env, force=False): self.project = build_env.project self._force = force self.target = self.project.artifact_path( - version=self.version.slug, - type_=self.type - ) + version=self.version.slug, type_=self.type) def force(self, **__): """An optional step to force a build even when nothing has changed.""" - log.info("Forcing a build") + log.info('Forcing a build') self._force = True def build(self): @@ -59,16 +62,16 @@ def move(self, **__): if os.path.exists(self.old_artifact_path): if os.path.exists(self.target): shutil.rmtree(self.target) - log.info("Copying %s on the local filesystem", self.type) + log.info('Copying %s on the local filesystem', self.type) shutil.copytree(self.old_artifact_path, self.target) else: - log.warning("Not moving docs, because the build dir is unknown.") + log.warning('Not moving docs, because the build dir is unknown.') def clean(self, **__): - """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) + log.info('Removing old artifact path: %s', self.old_artifact_path) def docs_dir(self, docs_dir=None, **__): """Handle creating a custom docs_dir if it doesn't exist.""" @@ -87,9 +90,11 @@ def create_index(self, extension='md', **__): """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)) + index_filename = os.path.join( + docs_dir, 'index.{ext}'.format(ext=extension)) if not os.path.exists(index_filename): - readme_filename = os.path.join(docs_dir, 'README.{ext}'.format(ext=extension)) + readme_filename = os.path.join( + docs_dir, 'README.{ext}'.format(ext=extension)) if os.path.exists(readme_filename): return 'README' else: @@ -112,5 +117,5 @@ def create_index(self, extension='md', **__): return 'index' def run(self, *args, **kwargs): - """Proxy run to build environment""" + """Proxy run to build environment.""" return self.build_env.run(*args, **kwargs) From f086390f3ce4e973b9b267edf2c3ff9141d80beb Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Mon, 25 Dec 2017 23:06:28 -0500 Subject: [PATCH 3/5] Less redundant sentence --- readthedocs/doc_builder/base.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/readthedocs/doc_builder/base.py b/readthedocs/doc_builder/base.py index e341e5ac600..415bd7faf72 100644 --- a/readthedocs/doc_builder/base.py +++ b/readthedocs/doc_builder/base.py @@ -106,8 +106,8 @@ def create_index(self, extension='md', **__): This is an autogenerated index file. -Please create a ``index.{ext}`` or ``README.{ext}`` file with your own content -under the root directory in your repository (or under ``/docs`` directory). +Please create an ``index.{ext}`` or ``README.{ext}`` file with your own content +under the root (or ``/docs``) directory in your repository. If you want to use another markup, choose a different builder in your settings. """ From 0efbd47fa43f563e5d0ce92b1a6388f176814a83 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 26 Dec 2017 15:52:33 -0500 Subject: [PATCH 4/5] Add link to the getting started guide --- readthedocs/doc_builder/base.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/readthedocs/doc_builder/base.py b/readthedocs/doc_builder/base.py index 415bd7faf72..8f2a62253a5 100644 --- a/readthedocs/doc_builder/base.py +++ b/readthedocs/doc_builder/base.py @@ -110,6 +110,9 @@ def create_index(self, extension='md', **__): under the root (or ``/docs``) directory in your repository. If you want to use another markup, choose a different builder in your settings. +Check out our `Getting Started Guide +`_ to become more +familiar with Read The Docs. """ index_file.write(index_text.format(dir=docs_dir, ext=extension)) From 1783311b6758729dfe05d477be48306229168bec Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 27 Dec 2017 17:13:08 -0500 Subject: [PATCH 5/5] Fix brand name --- readthedocs/doc_builder/base.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readthedocs/doc_builder/base.py b/readthedocs/doc_builder/base.py index 8f2a62253a5..d81565d9c7c 100644 --- a/readthedocs/doc_builder/base.py +++ b/readthedocs/doc_builder/base.py @@ -112,7 +112,7 @@ def create_index(self, extension='md', **__): If you want to use another markup, choose a different builder in your settings. Check out our `Getting Started Guide `_ to become more -familiar with Read The Docs. +familiar with Read the Docs. """ index_file.write(index_text.format(dir=docs_dir, ext=extension))