Merge branch 'master' into config-file-v2-docs

.gitignore

@@ -32,6 +32,7 @@ media/json
 media/man
 media/pdf
 media/static
+/static
 node_modules
 package-lock.json
 readthedocs/rtd_tests/builds

.travis.yml

@@ -20,6 +20,7 @@ cache:
   directories:
     - ~/.cache/pip
     - ~/.nvm/nvm.sh
+    - ~/.npm
 install:
   - ./scripts/travis/install_elasticsearch.sh
   - pip install tox-travis

CHANGELOG.rst

@@ -1,3 +1,60 @@
+Version 2.6.3
+-------------
+
+:Date: August 18, 2018
+
+Release to Azure!
+
+* `@davidfischer <http://github.com/davidfischer>`__: Add Sponsors list to footer (`#4424 <https://github.com/rtfd/readthedocs.org/pull/4424>`__)
+* `@stsewd <http://github.com/stsewd>`__: Cache node_modules to speed up CI (`#4484 <https://github.com/rtfd/readthedocs.org/pull/4484>`__)
+* `@xrmx <http://github.com/xrmx>`__: templates: mark missing string for translation on project edit (`#4518 <https://github.com/rtfd/readthedocs.org/pull/4518>`__)
+* `@ericholscher <http://github.com/ericholscher>`__: Performance improvement: cache version listing on the homepage (`#4526 <https://github.com/rtfd/readthedocs.org/pull/4526>`__)
+* `@agjohnson <http://github.com/agjohnson>`__: Remove mailgun from our dependencies (`#4531 <https://github.com/rtfd/readthedocs.org/pull/4531>`__)
+* `@davidfischer <http://github.com/davidfischer>`__: Improved ad block detection (`#4532 <https://github.com/rtfd/readthedocs.org/pull/4532>`__)
+* `@agjohnson <http://github.com/agjohnson>`__: Revert "Remove SelectiveFileSystemFolder finder workaround" (`#4533 <https://github.com/rtfd/readthedocs.org/pull/4533>`__)
+* `@davidfischer <http://github.com/davidfischer>`__: Slight clarification on turning off ads for a project (`#4534 <https://github.com/rtfd/readthedocs.org/pull/4534>`__)
+* `@davidfischer <http://github.com/davidfischer>`__: Fix the sponsor image paths (`#4535 <https://github.com/rtfd/readthedocs.org/pull/4535>`__)
+* `@agjohnson <http://github.com/agjohnson>`__: Update build assets (`#4537 <https://github.com/rtfd/readthedocs.org/pull/4537>`__)
+
+
+Version 2.6.2
+-------------
+
+:Date: August 14, 2018
+
+* `@davidfischer <http://github.com/davidfischer>`__: Custom domain clarifications (`#4514 <https://github.com/rtfd/readthedocs.org/pull/4514>`__)
+* `@trein <http://github.com/trein>`__: Use single quote throughout the file (`#4513 <https://github.com/rtfd/readthedocs.org/pull/4513>`__)
+* `@davidfischer <http://github.com/davidfischer>`__: Support ads on pallets themes (`#4499 <https://github.com/rtfd/readthedocs.org/pull/4499>`__)
+* `@davidfischer <http://github.com/davidfischer>`__: Only use HostHeaderSSLAdapter for SSL/HTTPS connections (`#4498 <https://github.com/rtfd/readthedocs.org/pull/4498>`__)
+* `@keflavich <http://github.com/keflavich>`__: Very minor English correction (`#4497 <https://github.com/rtfd/readthedocs.org/pull/4497>`__)
+* `@davidfischer <http://github.com/davidfischer>`__: All static media is run through "collectstatic" (`#4489 <https://github.com/rtfd/readthedocs.org/pull/4489>`__)
+* `@humitos <http://github.com/humitos>`__: Fix reST structure (`#4488 <https://github.com/rtfd/readthedocs.org/pull/4488>`__)
+* `@nijel <http://github.com/nijel>`__: Document expected delay on CNAME change and need for CAA (`#4487 <https://github.com/rtfd/readthedocs.org/pull/4487>`__)
+* `@davidfischer <http://github.com/davidfischer>`__: Allow enforcing HTTPS for custom domains (`#4483 <https://github.com/rtfd/readthedocs.org/pull/4483>`__)
+* `@davidfischer <http://github.com/davidfischer>`__: Add some details around community ad qualifications (`#4436 <https://github.com/rtfd/readthedocs.org/pull/4436>`__)
+* `@davidfischer <http://github.com/davidfischer>`__: Updates to manifest storage (`#4430 <https://github.com/rtfd/readthedocs.org/pull/4430>`__)
+* `@davidfischer <http://github.com/davidfischer>`__: Update alt domains docs with SSL (`#4425 <https://github.com/rtfd/readthedocs.org/pull/4425>`__)
+* `@agjohnson <http://github.com/agjohnson>`__: Add SNI support for API HTTPS endpoint (`#4423 <https://github.com/rtfd/readthedocs.org/pull/4423>`__)
+* `@davidfischer <http://github.com/davidfischer>`__: API v1 cleanup (`#4415 <https://github.com/rtfd/readthedocs.org/pull/4415>`__)
+* `@davidfischer <http://github.com/davidfischer>`__: Allow filtering versions by active (`#4414 <https://github.com/rtfd/readthedocs.org/pull/4414>`__)
+* `@mlncn <http://github.com/mlncn>`__: Fix broken link (`#4410 <https://github.com/rtfd/readthedocs.org/pull/4410>`__)
+* `@safwanrahman <http://github.com/safwanrahman>`__: [Fix #4407] Port Project Search for Elasticsearch 6.x (`#4408 <https://github.com/rtfd/readthedocs.org/pull/4408>`__)
+* `@davidfischer <http://github.com/davidfischer>`__: Add client ID to Google Analytics requests (`#4404 <https://github.com/rtfd/readthedocs.org/pull/4404>`__)
+* `@xrmx <http://github.com/xrmx>`__: projects: fix filtering in projects_tag_detail (`#4398 <https://github.com/rtfd/readthedocs.org/pull/4398>`__)
+* `@davidfischer <http://github.com/davidfischer>`__: Fix a proxy model bug related to ad-free (`#4390 <https://github.com/rtfd/readthedocs.org/pull/4390>`__)
+* `@humitos <http://github.com/humitos>`__: Release 2.6.1 (`#4389 <https://github.com/rtfd/readthedocs.org/pull/4389>`__)
+* `@davidfischer <http://github.com/davidfischer>`__: Do not access database from builds to check ad-free (`#4387 <https://github.com/rtfd/readthedocs.org/pull/4387>`__)
+* `@humitos <http://github.com/humitos>`__: Adapt YAML config integration tests (`#4385 <https://github.com/rtfd/readthedocs.org/pull/4385>`__)
+* `@stsewd <http://github.com/stsewd>`__: Set full `source_file` path for default configuration (`#4379 <https://github.com/rtfd/readthedocs.org/pull/4379>`__)
+* `@humitos <http://github.com/humitos>`__: Make `get_version` usable from a specified path (`#4376 <https://github.com/rtfd/readthedocs.org/pull/4376>`__)
+* `@humitos <http://github.com/humitos>`__: More tags when logging errors to Sentry (`#4375 <https://github.com/rtfd/readthedocs.org/pull/4375>`__)
+* `@humitos <http://github.com/humitos>`__: Check for 'options' in update_repos command (`#4373 <https://github.com/rtfd/readthedocs.org/pull/4373>`__)
+* `@safwanrahman <http://github.com/safwanrahman>`__: [Fix  #4333] Implement asynchronous search reindex functionality using celery (`#4368 <https://github.com/rtfd/readthedocs.org/pull/4368>`__)
+* `@stsewd <http://github.com/stsewd>`__: V2 of the configuration file (`#4355 <https://github.com/rtfd/readthedocs.org/pull/4355>`__)
+* `@davidfischer <http://github.com/davidfischer>`__: Remove the UID from the GA measurement protocol (`#4347 <https://github.com/rtfd/readthedocs.org/pull/4347>`__)
+* `@humitos <http://github.com/humitos>`__: Mount `pip_cache_path` in Docker container (`#3556 <https://github.com/rtfd/readthedocs.org/pull/3556>`__)
+* `@agjohnson <http://github.com/agjohnson>`__: Show subprojects in search results (`#1866 <https://github.com/rtfd/readthedocs.org/pull/1866>`__)
+
 Version 2.6.1
 -------------
 

docs/advertising/ethical-advertising.rst

@@ -157,7 +157,8 @@ Users can opt out of seeing paid advertisements on documentation pages:
 * Go to the drop down user menu in the top right of the Read the Docs dashboard and clicking **Settings** (https://readthedocs.org/accounts/edit/).
 * On the **Advertising** tab, you can deselect **See paid advertising**.
 
-Project owners can also disable advertisements for their projects. You can change these options:
+Project owners can also opt out of paid advertisements for their projects.
+You can change these options:
 
 * Click on your **Project** page (`/projects/<slug>/`)
 * Click the  **Admin** dashboard link 
@@ -166,7 +167,8 @@ Project owners can also disable advertisements for their projects. You can chang
 
 Project opt out options include:
 
-* Supporting us `financially <https://readthedocs.org/accounts/gold/subscription/?>`_ with Read the Docs Gold. This will disable all ads from showing on your project's documentation.
+* Supporting us `financially <https://readthedocs.org/accounts/gold/subscription/>`_ by becoming a Gold Member.
+  This will disable all ads from showing on your project's documentation.
 * Supporting us with `your time <http://docs.readthedocs.org/en/latest/contribute.html?>`_ by contributing to the project.
 * Moving to our `paid product <https://readthedocs.com/pricing/?>`_ over at readthedocs.com.
 * Opting out without doing any of the above. This will make us a little sad, but we understand not everyone has the means to contribute back.

docs/alternate_domains.rst

@@ -46,12 +46,23 @@ By default, when you setup a custom domain to host documentation at Read the Doc
 we will attempt to provision a domain validated SSL certificate for the domain.
 This service is generously provided by Cloudflare.
 
+After configuring your custom domain on Read the Docs,
+you can see the status of the certificate on the domain edit screen
+(**Project Admin > Domains > Edit Domain**).
+
+If your domain has configured CAA records, please do not forget to include
+Cloudflare CAA entries, see their `Certification Authority Authorization (CAA)
+FAQ <https://support.cloudflare.com/hc/en-us/articles/115000310832-Certification-Authority-Authorization-CAA-FAQ>`_.
+
 .. note::
 
     Some older setups configured a CNAME record pointing to ``readthedocs.org``
     or another variation. While these continue to resolve,
     they do not yet allow us to acquire SSL certificates for those domains.
-    Simply point the CNAME to ``readthedocs.io``.
+    Point the CNAME to ``readthedocs.io`` and re-request a certificate
+    by saving the domain (**Project Admin > Domains > Edit Domain**).
+
+    If you change the CNAME, the SSL certificate issuance can take about one hour.
 
 .. important::
 

docs/builds.rst

@@ -15,7 +15,8 @@ Our current build limits are:
 We can increase build limits on a per-project basis,
 if you provide a good reason your documentation needs more resources.
 
-You can see the current Docker build images that we use in our `docker repository <https://github.com/rtfd/readthedocs-docker-images>`_. `Docker Hub <https://hub.docker.com/r/readthedocs/build/>`_ also shows the latest set of images that have been built.
+You can see the current Docker build images that we use in our `docker repository <https://github.com/rtfd/readthedocs-docker-images>`_.
+`Docker Hub <https://hub.docker.com/r/readthedocs/build/>`_ also shows the latest set of images that have been built.
 
 Currently in production we're using the ``readthedocs/build:2.0`` docker image as our default image.
 
@@ -46,24 +47,35 @@ we will first look for a ``mkdocs.yml`` file in the root of your repository.
 If we don't find one,
 we will generate one for you.
 
-Then MkDocs will build any files with a ``.md`` extension.
+Then MkDocs will build any files with a ``.md`` extension within the directory specifed as ``docs_dir`` in the ``mkdocs.yml``. 
+
+If no ``mkdocs.yml`` was found in the root of your repository and we generated one for you, 
+Read the Docs will attempt to set ``docs_dir`` by sequentially searching for a  ``docs``, ``doc``, ``Doc``, or ``book`` directory. 
+The first of these directories that exists and contains files with a ``.md`` extension will be set to ``docs_dir`` within ``mkdocs.yml``,
+and MkDocs will build the ``.md`` files in that directory. 
 As MkDocs doesn't support automatic PDF generation, 
 Read the Docs cannot create a PDF version of your documentation with the *Mkdocs* option.
 
 Understanding what's going on
 -----------------------------
 
-Understanding how Read the Docs builds your project will help you with debugging the problems you have with the site. It should also allow you to take advantage of certain things that happen during the build process.
+Understanding how Read the Docs builds your project will help you with debugging the problems you have with the site.
+It should also allow you to take advantage of certain things that happen during the build process.
 
-The first step of the process is that we check out your code from the repository you have given us. If the code is already checked out, we update the copy to the branch that you have specified in your projects configuration.
+The first step of the process is that we check out your code from the repository you have given us.
+If the code is already checked out, we update the copy to the branch that you have specified in your projects configuration.
 
 Then we build the proper backend code for the type of documentation you've selected.
 
-If you have the *Install Project* option enabled, we will run ``setup.py install`` on your package, installing it into a virtual environment. You can also define additional packages to install with the *Requirements File* option.
+If you have the *Install Project* option enabled, we will run ``setup.py install`` on your package, installing it into a virtual environment.
+You can also define additional packages to install with the *Requirements File* option.
 
-When we build your documentation, we run `sphinx-build -b html . _build/html`, where `html` would be replaced with the correct backend. We also create man pages and pdf's automatically based on your project.
+When we build your documentation, we run ``sphinx-build -b html . _build/html``,
+where ``html`` would be replaced with the correct backend.
+We also create pdf's and ePub's automatically based on your project.
 
-Then these files are copied across to our application servers from the build server. Once on the application servers, they are served from nginx. 
+Then these files are copied across to our application servers from the build server.
+Once on the application servers, they are served from nginx. 
 
 An example in code:
 
@@ -78,7 +90,7 @@ An example in code:
     copy_files(artifact_dir)
     
 
-Builder Responsibility
+Builder responsibility
 ----------------------
 
 Builders have a very specific job.
@@ -88,18 +100,76 @@ The artifacts should end up in ``self.version.project.artifact_path(version=self
 Where ``type`` is the name of your builder.
 All files that end up in the artifact directory should be in their final form.
 
-Packages installed in the build environment
--------------------------------------------
-
-The build server does have a select number of C libraries installed, because they are used across a wide array of python projects. We can't install every C library out there, but we try and support the major ones. We currently have the following libraries installed:
-
-    * doxygen
-    * LaTeX (texlive-full)
-    * libevent (libevent-dev)
-    * dvipng
-    * graphviz
-    * libxslt1.1
-    * libxml2-dev
+The build environment
+---------------------
+
+The build process is executed inside Docker containers,
+by default the image used is ``readthedocs/build:2.0``,
+but you can change that using a :doc:`configuration file <yaml-config>`.
+
+.. note::
+
+   The Docker images have a select number of C libraries installed,
+   because they are used across a wide array of python projects.
+   We can't install every C library out there,
+   but we try and support the major ones.
+
+.. tip::
+
+   If you want to know the specific version of a package that is installed in the image
+   you can check the `Ubuntu package search page <https://packages.ubuntu.com/>`__.
+
+2.0 (stable)
+~~~~~~~~~~~~
+
+:O.S: Ubuntu 16.04
+:Conda: Miniconda 4.3.31
+:Python:
+  * ``m2crypto``
+  * ``matplolib``
+  * ``numpy``
+  * ``pandas``
+  * ``pip``
+  * ``scipy``
+:Other packages:
+  * ``doxygen``
+  * ``graphviz``
+  * ``libevent``
+  * ``libjpeg``
+  * ``libxml2-dev``
+  * ``libxslt1.1``
+  * ``pandoc``
+  * ``textlive-full``
+
+`More details <https://github.com/rtfd/readthedocs-docker-images/blob/releases/2.x/Dockerfile>`__
+
+3.0 (latest)
+~~~~~~~~~~~~
+
+:O.S: Ubuntu 16.04
+:Conda: Miniconda 4.4.10
+:Python:
+  * ``matplolib``
+  * ``numpy``,
+  * ``pandas``
+  * ``pip``
+  * ``scipy``
+:JavaScript:
+  * ``jsdoc``
+  * ``nodejs``
+  * ``npm``
+:Other packages:
+  * ``doxygen``
+  * ``libevent-dev``
+  * ``libgraphviz-dev``
+  * ``libjpeg``
+  * ``libxml2-dev``
+  * ``libxslt1-dev``
+  * ``pandoc``
+  * ``plantuml``
+  * ``textlive-full``
+
+`More details <https://github.com/rtfd/readthedocs-docker-images/blob/releases/3.x/Dockerfile>`__
 
 Writing your own builder
 ------------------------

docs/guides/adding-custom-css.rst

@@ -22,4 +22,4 @@ The same method can be used to add additional scripts that might override
 previously initialized scripts::
 
     def setup(app):
-        app.add_javascript("js/custom.js")
+        app.add_javascript('js/custom.js')

docs/guides/build-using-too-many-resources.rst

@@ -13,7 +13,7 @@ Reduce formats you're building
 You can change the formats of docs that you're building with our :doc:`/config-file/index`,
 see :ref:`config-file/v2:formats`.
 
-In particular, the `htmlzip` takes up a decent amount of memory and time,
+In particular, the ``htmlzip`` takes up a decent amount of memory and time,
 so disabling that format might solve your problem.
 
 Reduce documentation build dependencies
@@ -24,3 +24,31 @@ If there are extra packages that you don't need for building docs,
 you can create a custom requirements file just for documentation.
 This should speed up your documentation builds,
 as well as reduce your memory footprint.
+
+Use pip when possible
+---------------------
+
+If you don't need ``conda`` to create your *documentation* environment,
+consider using ``pip`` instead since ``conda`` could `require too much memory`_ to calculate the dependency tree
+when using multiple channels.
+
+.. _require too much memory: https://github.com/conda/conda/issues/5003>
+
+
+.. tip::
+
+   Even though your *project* environment is created with ``conda``, it may be not necessary for the *documentation* environment.
+   That is, to build the documentation is probably that you need fewer Python packages than to use your library itself.
+   So, in this case, you could use ``pip`` to install those fewer packages instead of creating a big environment with ``conda``.
+
+
+Use system site-packages for pre-installed libs
+-----------------------------------------------
+
+There are a few libraries that Read the Docs has already installed (scipy, numpy, matplotlib, pandas, etc)
+in the Docker image used to build your docs. You can check the updated list of pre-installed libraries in the `Docker image repository`_.
+
+To use these pre-installed libraries and avoid consuming time re-downloading/compiling them,
+you can use the :ref:`yaml-config:python.use_system_site_packages` option to have access to them.
+
+.. _Docker image repository: https://github.com/rtfd/readthedocs-docker-images

docs/i18n.rst

@@ -147,7 +147,7 @@ filters or accessing object attributes. You can't do that within the ``{%
 blocktrans %}`` block, so you need to bind the expression to a local variable
 first::
 
-    {% blocktrans with revision.created_date|timesince as timesince %}
+    {% blocktrans trimmed with revision.created_date|timesince as timesince %}
     {{ revision }} {{ timesince }} ago
     {% endblocktrans %}
 
@@ -157,13 +157,20 @@ first::
 counter with the name ``count`` and provide a plural translation after the ``{%
 plural %}`` tag::
 
-    {% blocktrans with amount=article.price count years=i.length %}
+    {% blocktrans trimmed with amount=article.price count years=i.length %}
     That will cost $ {{ amount }} per year.
     {% plural %}
     That will cost $ {{ amount }} per {{ years }} years.
     {% endblocktrans %}
 
 
+.. note::
+
+   The previous multi-lines examples also use the ``trimmed`` option.
+   This removes newline characters and replaces any whitespace at the beginning and end of a line,
+   helping translators when translating these strings.
+
+
 Strings in Python
 -----------------
 
@@ -287,3 +294,22 @@ the `Compiling to MO`_ section).
 
 For more information about the ``tx`` command, read the `Transifex client's
 help pages <http://help.transifex.com/features/client/>`_.
+
+
+.. note::
+
+   For the Read the Docs community site, we use a `fabric script`_ to follow this process:
+
+   .. _fabric script: https://github.com/rtfd/readthedocs.org/blob/master/fabfile.py
+
+   #. Update files and push sources (English) to Transifex:
+
+      .. code-block:: console
+
+         $ fab i18n_push_source
+
+   #. Pull changes (new translations) from Transifex:
+
+      .. code-block:: console
+
+         $ fab i18n_pull