Merge branch 'master' into lint-raise-profile

Author: ericholscher

.gitignore

@@ -7,6 +7,8 @@
 .idea
 .vagrant
 .tox
+.rope_project/
+.ropeproject/
 _build
 cnames
 bower_components/
@@ -33,3 +35,5 @@ prod_artifacts
 wheelhouse
 whoosh_index
 xml_output
+public_cnames
+public_symlinks

.travis.yml

@@ -16,6 +16,6 @@ after_success:
 notifications:
   slack:
     rooms:
-      - readthedocs:y3hjODOi7EIz1JAbD1Zb41sz#general
+      - readthedocs:y3hjODOi7EIz1JAbD1Zb41sz#random
     on_success: change
     on_failure: always

README.rst

@@ -60,4 +60,4 @@ when you push to GitHub.
 .. |docs| image:: https://readthedocs.org/projects/docs/badge/?version=latest
     :alt: Documentation Status
     :scale: 100%
-    :target: https://readthedocs.org/projects/docs/
+    :target: https://docs.readthedocs.org/en/latest/?badge=latest

bower.json

@@ -14,10 +14,16 @@
     "tests"
   ],
   "dependencies": {
-    "jquery": "~2.0.3",
+    "jquery": "2.0.3",
     "underscore": "~1.7.0",
     "readthedocs-client": "https://github.com/agjohnson/readthedocs-client-js.git",
+    "sphinx-rtd-theme": "https://github.com/snide/sphinx-rtd-theme.git#0.1.9",
     "knockout": "~3.3.0",
-    "jquery.payment": "~1.2.3"
+    "jquery.payment": "~1.3.0",
+    "jquery-migrate": "~1.2.1",
+    "jquery-ui": "1.8.23"
+  },
+  "resolutions": {
+    "jquery": "2.0.3"
   }
 }

deploy/delete_stale_projects.py

@@ -1,7 +1,7 @@
 import shutil
 import os
 
-from projects.models import Project
+from readthedocs.projects.models import Project
 
 slugs = [p.slug for p in Project.objects.all()]
 build_projects = os.listdir('/home/docs/checkouts/readthedocs.org/user_builds/')

deploy/flask-redirects.py

@@ -1,3 +1,7 @@
+"""
+A flask app for redirecting documentation from the root / URL.
+"""
+
 import json
 
 from flask import Flask, make_response, redirect, request

docs/alternate_domains.rst

@@ -6,7 +6,7 @@ Read the Docs supports a number of custom domains for your convenience. Shorter
 Subdomain Support
 ------------------
 
-Every project has a subdomain that is available to serve it's documentation. If you go to <slug>.readthedocs.org, it should show you the latest version of documentation. A good example is http://pip.readthedocs.org
+Every project has a subdomain that is available to serve its documentation. If you go to <slug>.readthedocs.org, it should show you the latest version of documentation. A good example is http://pip.readthedocs.org
 
 .. note:: If you have an old project that has an underscore (_) in the name, it will use a subdomain with a hypen (-).
           `RFC 1035 <http://tools.ietf.org/html/rfc1035>`_ has more information on valid subdomains.

docs/builds.rst

@@ -40,6 +40,8 @@ and then default to the top-level of your documentation.
 Then Mkdocs will build any files with an ``.md`` extension.
 If you have a ``README.md``,
 it will be transformed into an ``index.md`` automatically.
+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
 -----------------------------
@@ -50,7 +52,7 @@ The first step of the process is that we check out your code from the repository
 
 Then we build the proper backend code for the type of documentation you've selected.
 
-If you have the *Use Virtualenv* 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.
 
@@ -84,6 +86,7 @@ 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

docs/canonical.rst

@@ -23,7 +23,7 @@ This means that when Google indexes ``http://fabric-docs.readthedocs.org``, it w
 Enabling
 --------
 
-You can set the canonical URL for your project in the Project Admin page. Check your `dashboard`_ for a list of your projects.
+You can set the canonical URL for your project in the Project Admin page. Check your `Domains` tab for the domains that we know about.
 
 Implementation
 --------------

docs/conda.rst

@@ -0,0 +1,45 @@
+Conda Support
+=============
+
+.. warning:: This feature is in a beta state.
+             Please file an `issue`_ if you find anything wrong.
+
+Read the Docs supports Conda as an environment management tool,
+along with Virtualenv.
+Conda support is useful for people who depend on C libraries,
+and need them installed when building their documentation.
+
+This work was funded by `Clinical Graphics`_ -- many thanks for their support of Open Source.
+
+Activating Conda
+----------------
+
+Conda Support is the first feature enabled with :doc:`yaml-config`.
+You can enable it by creating a `readthedocs.yml` file in the root of your repsitory with the contents:
+
+.. code-block:: yaml
+
+	conda:
+	    file: environment.yml
+
+This Conda environment will also have Sphinx and other build time dependencies installed.
+It will use the same order of operations that we support currently:
+
+* Environment Creation (``conda create``)
+* Dependency Installation (Sphinx)
+* User Package Installation (``conda env update``)
+
+Custom Installs
+---------------
+
+If you are running a custom installation of Read the Docs,
+you will need the ``conda`` executable installed somewhere on your ``PATH``.
+Because of the way ``conda`` works,
+we can't safely install it as a normal dependency into the normal Python virtualenv.
+
+.. warning:: Installing conda into a virtualenv will override the ``activate`` script,
+             making it so you can't properly activate that virtualenv anymore.
+
+.. _issue: https://github.com/rtfd/readthedocs.org/issues
+.. _Clinical Graphics: https://www.clinicalgraphics.com/
+

docs/custom_installs/local_rtd_vm.rst

@@ -47,7 +47,7 @@ Possible Error and Resolution
 **Resolution**: Run the following commands. ::
 
     $ sudo apt-get update
-    $ sudo apt-get install python2.7-dev tk8.5 tcl8.5 tk8.5-dev tcl8.5-dev
+    $ sudo apt-get install python2.7-dev tk8.5 tcl8.5 tk8.5-dev tcl8.5-dev libxml2-devel libxslt-devel
     $ sudo apt-get build-dep python-imaging --fix-missing 
 
 2. Configure the RTD Server and Superuser.

docs/design.rst

@@ -1,4 +1,4 @@
-.. _designing-read-the-docs: 
+.. _designing-read-the-docs:
 
 Designing Read the Docs
 =======================
@@ -23,7 +23,7 @@ for a quick overview of the currently available styles.
 This way you can quickly get started writing HTML -- or if you're
 modifying existing styles you can get a quick idea of how things
 will change site-wide.
-   
+
 Typekit Fonts
 -------------
 
@@ -55,15 +55,15 @@ Contributing
 ------------
 
 Contributions should follow the :ref:`contributing-to-read-the-docs` guidelines where applicable -- ideally you'll
-create a pull request against the `Read the Docs Github project`_ from your forked repo and include
+create a pull request against the `Read the Docs GitHub project`_ from your forked repo and include
 a brief description of what you added / removed / changed, as well as an attached image (you can just
 take a screenshot and drop it into the PR creation form) of the effects of your changes.
 
 There's not a hard browser range, but your design changes should work reasonably well across all major
 browsers, IE8+ -- that's not to say it needs to be pixel-perfect in older browsers! Just avoid
 making changes that render older browsers utterly unusable (or provide a sane fallback).
 
-.. _Read the Docs Github project: https://github.com/rtfd/readthedocs.org/pulls
+.. _Read the Docs GitHub project: https://github.com/rtfd/readthedocs.org/pulls
 
 
 

docs/faq.rst

@@ -66,6 +66,8 @@ Of course, replacing `MOCK_MODULES` with the modules that you want to mock out.
 
         from mock import Mock as MagicMock
 
+If such libraries are installed via ``setup.py``, you also will need to remove all the C-dependent libraries from your ``install_requires`` in the RTD environment.
+
 `Client Error 401` when building documentation
 ----------------------------------------------
 
@@ -189,3 +191,35 @@ are `numpydoc <https://github.com/numpy/numpydoc>`_ and
 ``napoleon`` is able to handle both docstring formats. Its default
 output more closely matches the format of standard Sphinx annotations,
 and as a result, it tends to look a bit better with the default theme.
+
+Can I document a python package that is not at the root of my repository?
+-------------------------------------------------------------------------
+
+Yes. The most convenient way to access a python package for example via
+`Sphinx's autoapi`_ in your documentation is to use the *Install your project
+inside a virtualenv using ``setup.py install``* option in the admin panel of
+your project. However this assumes that your ``setup.py`` is in the root of
+your repository.
+
+If you want to place your package in a different directory or have multiple
+python packages in the same project, then create a pip requirements file. You
+can specify the relative path to your package inside the file.
+For example you want to keep your python package in the ``src/python``
+directory, then create a ``requirements.readthedocs.txt`` file with the
+following contents::
+
+    src/python/
+
+Please note that the path must be relative to the file. So the example path
+above would work if the file is in the root of your repository. If you want to
+put the requirements in a file called ``requirements/readthedocs.txt``, the
+contents would look like::
+
+    ../python/
+
+After adding the file to your repository, go to the *Advanced Settings* in
+your project's admin panel and add the name of the file to the *Requirements
+file* field.
+
+.. _Sphinx's autoapi: http://sphinx-doc.org/ext/autodoc.html
+.. _pip requirements file: https://pip.pypa.io/en/stable/user_guide.html#requirements-files

docs/features.rst

@@ -3,17 +3,17 @@ Read the Docs features
 
 This will serve as a list of all of the features that Read the Docs currently has. Some features are important enough to have their own page in the docs, others will simply be listed here.
 
-Github and Bitbucket Integration
+GitHub and Bitbucket Integration
 --------------------------------
 
-We now support linking by default in the sidebar. It links to the page on your host, which should help people quickly update typos and send pull requests to contribute to project documentation. 
+We now support linking by default in the sidebar. It links to the page on your host, which should help people quickly update typos and send pull requests to contribute to project documentation.
 
 More information can be found in the :doc:`vcs` page.
 
 Auto-updating
 -------------
 
-The :doc:`webhooks` page talks about the different ways you can ping RTD to let us know your project has been updated. We have official support for Github, and anywhere else we have a generic post-commit hook that allows you to POST to a URL to get your documentation built.
+The :doc:`webhooks` page talks about the different ways you can ping RTD to let us know your project has been updated. We have official support for GitHub, and anywhere else we have a generic post-commit hook that allows you to POST to a URL to get your documentation built.
 
 Internationalization
 --------------------
@@ -30,12 +30,12 @@ More information can be found in the :doc:`canonical` page.
 Versions
 --------
 
-We can build multiple versions of your documentation. Look on the "Versions" page 
-of your project's admin (using the nav on the left) to find a list of available versions 
-that we've inferred from the tags and branches in your source control system (according to 
-the support matrix below). On the Versions page you can tell us which versions you'd like us 
-to build docs for, whether each should be public, protected, or private, and what the default 
-version should be (we'll redirect there when someone hits your main project page, e.g., 
+We can build multiple versions of your documentation. Look on the "Versions" page
+of your project's admin (using the nav on the left) to find a list of available versions
+that we've inferred from the tags and branches in your source control system (according to
+the support matrix below). On the Versions page you can tell us which versions you'd like us
+to build docs for, whether each should be public, protected, or private, and what the default
+version should be (we'll redirect there when someone hits your main project page, e.g.,
 http://my-project.rtfd.org/).
 
 Version Control Support Matrix

docs/getting_started.rst

@@ -11,7 +11,7 @@ If you are already using Sphinx or Markdown for your docs, skip ahead to
 Write Your Docs
 ---------------
 
-You have two options for format for your documentation:
+You have two options for formatting your documentation:
 
 * :ref:`in-rst`
 * :ref:`in-markdown`
@@ -38,7 +38,7 @@ Run ``sphinx-quickstart`` in there::
     $ cd docs
     $ sphinx-quickstart
 
-This will walk you through creating the basic configuration; in most cases, you
+This quick start will walk you through creating the basic configuration; in most cases, you
 can just accept the defaults. When it's done, you'll have an ``index.rst``, a
 ``conf.py`` and some other files. Add these to revision control.
 

docs/index.rst

@@ -44,6 +44,7 @@ Information about development is also available:
    features
    support
    faq
+   yaml-config
 
 
 .. _feature-docs:
@@ -58,6 +59,7 @@ Information about development is also available:
    alternate_domains
    localization
    vcs
+   conda
    canonical
    single_version
    privacy
@@ -83,7 +85,6 @@ Information about development is also available:
    settings
    i18n
    issue-labels
-   api
 
 .. _business-docs:
 

docs/install.rst

@@ -78,7 +78,7 @@ Then please create a superuser account for Django::
 
     ./manage.py createsuperuser
 
-By now, it is the right time to load in a couple users and a test projects::
+By now, it is the right time to load in a couple users and a test project::
 
     ./manage.py loaddata test_data
 

docs/locale/da/LC_MESSAGES/design.po

@@ -1,7 +1,7 @@
 # SOME DESCRIPTIVE TITLE.
 # Copyright (C) 2010, Eric Holscher, Charlie Leifer, Bobby Grace
 # This file is distributed under the same license as the Read The Docs package.
-# 
+#
 # Translators:
 msgid ""
 msgstr ""
@@ -123,7 +123,7 @@ msgstr ""
 msgid ""
 "Contributions should follow the :ref:`contributing-to-read-the-docs` "
 "guidelines where applicable -- ideally you'll create a pull request against "
-"the `Read the Docs Github project`_ from your forked repo and include a "
+"the `Read the Docs GitHub project`_ from your forked repo and include a "
 "brief description of what you added / removed / changed, as well as an "
 "attached image (you can just take a screenshot and drop it into the PR "
 "creation form) of the effects of your changes."

docs/locale/da/LC_MESSAGES/features.po

@@ -1,7 +1,7 @@
 # SOME DESCRIPTIVE TITLE.
 # Copyright (C) 2010, Eric Holscher, Charlie Leifer, Bobby Grace
 # This file is distributed under the same license as the Read The Docs package.
-# 
+#
 # Translators:
 msgid ""
 msgstr ""
@@ -32,7 +32,7 @@ msgstr ""
 
 # b76f9583f25246b88eb15790dbfed33c
 #: ../../features.rst:7
-msgid "Github and Bitbucket Integration"
+msgid "GitHub and Bitbucket Integration"
 msgstr ""
 
 # 8d0f0e8a31304c2e9326610f43e7cd44
@@ -58,7 +58,7 @@ msgstr ""
 msgid ""
 "The :doc:`webhooks` page talks about the different ways you can ping RTD to "
 "let us know your project has been updated. We have official support for "
-"Github, and anywhere else we have a generic post-commit hook that allows you"
+"GitHub, and anywhere else we have a generic post-commit hook that allows you"
 " to POST to a URL to get your documentation built."
 msgstr ""
 

docs/locale/da/LC_MESSAGES/support.po

@@ -1,7 +1,7 @@
 # SOME DESCRIPTIVE TITLE.
 # Copyright (C) 2010, Eric Holscher, Charlie Leifer, Bobby Grace
 # This file is distributed under the same license as the Read The Docs package.
-# 
+#
 # Translators:
 msgid ""
 msgstr ""
@@ -32,7 +32,7 @@ msgstr ""
 msgid ""
 "The easiest way to get help with the project is to join the ``#readthedocs``"
 " channel on Freenode_. We hang out there and you can get real-time help with"
-" your projects.  The other good way is to open an issue on Github_."
+" your projects.  The other good way is to open an issue on GitHub_."
 msgstr ""
 
 # 56a196d98e104204ad6849fdc78b9b4e