Switch RTD to setup_py_install

pip_install on RTD is very buggy. See
readthedocs/readthedocs.org#3925
readthedocs/readthedocs.org#3025

README.md

@@ -13,7 +13,7 @@ Features
 * Python 3 only. Although it would be straightforward to also add Python 2 support to your package by hand.
 * The actual package code is in a `src` directory. See <https://blog.ionelmc.ro/2014/05/25/python-packaging/#the-structure> for the reasoning behind this.
 * [Travis CI](https://travis-ci.org) support.
-* Sphinx/Read-the-docs support
+* Sphinx/Read-the-docs support. This includes optional use of the [better_apidoc](https://github.com/goerz/better-apidoc) tool for generating API documentation with templates.
 * Mandatory testing with [pytest](https://docs.pytest.org)
 * Environment management through [`conda`](https://conda.io/docs/)
 * Development tasks are organized in a Makefile. Run `make help` inside the generated project for details.
@@ -69,11 +69,36 @@ Post-Setup
 
 After you generate a new project from the cookiecutter template, you should do the following:
 
-*   Declare dependencies in `setup.py`, both for installation and development (testing).  There are no additional pip requirement files (I find them unnecessary). If you are using `conda` and an `environment_manager`, you may list any dependency that you know has a `conda packages` in `CONDA_PACKAGES` in `Makefile`. Also, if you are using Travis CI (`use_travis`), you should add the same packages in the `install` section of `.travis.yml`. Likewise, if you are using readthedocs to host your documentation, you will have to add the conda packages to `docs/rtd_environment.yml`. Any dependencies not installed as conda packages will still automatically be installed via `pip`, so the use of conda packages is optional. However, if you do use conda packages, you must manually ensure that the list of conda packages in the various locations (`Makefile`, `.travis.yml`, and `docs/rtd_environment`) stays in synch.
+*   Declare dependencies in `setup.py`, both for installation and development (testing).  There are no additional [pip requirement files](https://pip.pypa.io/en/stable/user_guide/#requirements-files) (I find them unnecessary).
+
+*   If you are using `conda` and an `environment_manager`, you may list any dependency that you know has a conda package in `CONDA_PACKAGES` in `Makefile`. Also, if you are using Travis CI (`use_travis`), you should add the same packages in the `install` section of `.travis.yml`. Any dependencies not installed as conda packages will still automatically be installed via `pip`, so the use of conda packages is optional. However, if you do use conda packages, you must manually ensure that the list of conda packages in the various locations (`Makefile`, `.travis.yml`) stays in sync.
+
+*   If you are using ReadTheDocs (RTD) with conda to host your documentation, you will have to specify the build environment for the documentation in `docs/rtd_environment.yml`.  Packages that are available through conda can be listed directly, other packages must be listed in a pip section. For example,
+
+        channels:
+          - defaults
+        dependencies:
+          - python=3.6
+          - anaconda
+          - pip:
+              - better-apidoc
+              - trajectorydata
+              - git+https://github.com/mabuchilab/QNET.git@develop#egg=QNET-2.0.0-dev
+
+    In general, RTD needs only a minimal number of dependencies (*not* everything required to run the tests). Specifically, you must not include any `sphinx-*` dependencies in `docs/rtd_environment.yml` -- these are installed automatically by the RTD build process. RTD will not take into account dependencies listed in `setup.py`
+
+*   Review the custom RTD templates in `docs/_templates`
+
 *   If you didn't do so during project creation, initialize git and push the project to Github
+
 *   If you are using the git-flow branching model, you *must* configure this on Github. Go to the "Settings" for the project, then "Branches", and switch the "Default branch" from "master", to "develop". You may consider protecting the master branch.
+
 *   Activate Travis CI. The easiest way to do this is to click on the `build|unknown` badge in the README on Github
+
 *   Activate ReadTheDocs. Log in to <https://readthedocs.org/dashboard/>, and click the "Import a Project" button. You shouldn't have to do any configuration, as everything is set up through the `readthedocs.yml` and `docs/rtd_environment.yml` files.
+
 *   Activate Coveralls. Log in to <https://coveralls.io>, and click on "Add Repo". Not that coverage data is only uploaded if all tests pass successfully!
+
 *   If the package should be registered on PyPI, upload it. You can do this with `make release`. It is *strongly* recommended that you first try `make test-release` to upload the package to `test.pypi.org`.
+
 *   Review the classifiers in `setup.py`. The full list of PyPI classifiers can be found [here](https://pypi.python.org/pypi?:action=list_classifiers).

{{cookiecutter.project_slug}}/docs/rtd_environment.yml

@@ -1,10 +1,13 @@
 name: py{%if cookiecutter.support_py36 == 'y' %}36{% elif cookiecutter.support_py35 == 'y' %}35{% elif cookiecutter.support_py34 == 'y' %}34{% else %}3{% endif %}
 channels:
   - defaults
-  - conda-forge
 dependencies:
   - python={%if cookiecutter.support_py36 == 'y' %}3.6{% elif cookiecutter.support_py35 == 'y' %}3.5{% elif cookiecutter.support_py34 == 'y' %}3.4{% else %}3{% endif %}
 {%- set pkg_list = cookiecutter.conda_packages.split() -%}
 {%- for pkg in pkg_list %}
   - {{ pkg }}
 {%- endfor %}
+{%- if cookiecutter.better_apidoc == 'y' %}
+  - pip:
+      - better-apidoc
+{% endif %}

{{cookiecutter.project_slug}}/readthedocs.yml

@@ -8,7 +8,8 @@ build:
     image: latest
 python:
    version: {%if cookiecutter.support_py36 == 'y' %}3.6{% elif cookiecutter.support_py35 == 'y' %}3.5{% elif cookiecutter.support_py34 == 'y' %}3.4{% else %}3{% endif %}
-   setup_py_install: false
-   pip_install: true
-   extra_requirements:
-        - dev
+   # Note that pip_install is buggy, but setup_py_install will not take into
+   # account any dependencies from setup.py. *All* dependencies must be
+   # declared in docs/rtd_environment.yml
+   setup_py_install: true
+   pip_install: false