Added documentation for using a pip requirements file.

docs/faq.rst

@@ -184,6 +184,8 @@ are `numpydoc <https://github.com/numpy/numpydoc>`_ and
 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.
 
+.. _faq_document_package_not_at_root:
+
 Can I document a python package that is not at the root of my repository?
 -------------------------------------------------------------------------
 

docs/guides/using-requirements-file.rst

@@ -0,0 +1,117 @@
+Using a Requirements File
+=========================
+
+The requirements file option is useful in the following scenarios:
+ - You are using external packages, extensions, and themes that you need to include in your documentation project
+ - You have enabled the install project in a virtual environment option, but your package's setup.py file is not in the root directory.
+ - You have multiple python packages in your project and you wish to document them.
+
+-----------------------------
+Using a pip requirements file
+-----------------------------
+
+Creating the requirements file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You are using external packages, extensions, and themes that you need to include in your documentation project
+---------------------------------------------------------------------------------------------------------------
+
+Read the Docs supports adding specific functionality, and themes to tailor the behavior and appearance
+of your project's documentation. This is done by specifying a list of the packages, extensions, themes, to be used,
+and their versions, during the documentation build process.
+
+For example, one can specify which version of *Sphinx* to use, which theme they would like to use,
+what extensions they would like to add and so on.
+
+To do this, one can create a list of requirements and save it in a requirements file.
+
+Since *RTD* uses Python language to build the workflow which automatically converts and hosts your project's
+documentation, and uses various python packages for this, the requirments file is the same as any standard python project.
+Read the Docs installs them in a virtual environment using pip, the standard python package manager.
+
+In-fact, it is helpful to think of your documentation on readthedocs as a sub-project written in python,
+within your main project's repo.
+
+To use the requirements file:
+Create a text file with a sensible name in the root directory of your documentation directory. For example::
+
+    docs/requirements.txt
+    docs/requirements-docs.txt
+
+This is a standard python requirements file. If you know how to use that, this is the same thing. If not, read on.
+In this file, list all the packages (one package per line) that you require for building your documentation.
+Make sure to specify their appropriate version.
+
+For example, say you wish to only use Sphinx version 1.1.x and the sphinx_rtd_theme with a minimum version of 0.1.9.
+You are also using external extensions, for example, the napolean extension, (make sure to specify them in
+the extensions list in conf.py file), then your requirements file might look something like this:
+
+::
+
+	# <insert optional comment explaining why this package or version is a requirement>
+	sphinx == 1.1.*
+	sphinx_rtd_theme >= 0.1.9
+	sphinxcontrib-napolean
+
+
+You have enabled the install project in a virtual environment option, but your package's setup.py file is not in the root directory.
+---------------------------------------------------------------------------------------------------------------------------------------
+OR
+--
+You have multiple python packages in your project and you wish to document them.
+--------------------------------------------------------------------------------
+
+If you enable the option to install your project in a virtual environment, RTD automatically uses
+your project's setup.py file to install the packages. For this to work, the ``setup.py`` file must be
+in the root directory of your project.
+
+However, if you want to place your packages at a different location from the project's root directory,
+or your project has multiple python packages that you wish to document, then you can create a requirements file
+and specify the relative paths to your packages inside that file.
+
+For example, if you want to keep your python package in the ``src/python`` directory, located at the root of your project,
+create a ``requirements.readthedocs.txt`` file in your project root pointing to this path.
+Make sure that the path to the packages' root directory is relative to the path of the ``requirements.readthedocs.txt`` file.
+
+So if the requirements file is at the project root:: 
+
+    /requirements.readthedocs.txt
+
+its content will be::
+
+    src/python/
+
+If you want to put the requirements in the file::
+
+    requirements/readthedocs.txt
+
+its contents will be::
+
+    ../python/
+
+Also see :ref:`faq_document_package_not_at_root`
+
+Using the requirements file via the project admin's web interface
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Once the requirements file has been created;
+
+- Login to Read the Docs as project admin.
+- Select the project from My Projects.
+- Go to ``Admin > Advanced Settings > Requirements file``.
+- Specify the path of the requirements file you just created. The path should be relative to the root directory of the documentation project.
+
+Using the requirements file via the YAML configuration file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Documentation builds can be configured using a config.py file or using a YAML (.yml) file. 
+
+.. warning:: Using a YAML file to setup build config is a feature in a beta state. Please file an `issue`_ if you find anything malfunctioning.
+
+
+The YAML file should be named ``readthedocs.yml`` or ``.readthedocs.yml`` and should be located in the root directory of the project. In the file, you can add a section ``requirements_file``, where the path to the requirements file can be specified
+
+.. code-block:: yaml
+
+    requirements_file: requirements/readthedocs.txt
+
+
+.. _issue: : https://github.com/rtfd/readthedocs.org/issues