Note the dont-merge label. I just wanted to discuss the issues with either approach.

Previous comments that were addressed in later changes:

This fits within the Sphinx construct and would allow our docs to be built on readthedocs.org.

Unfortunately, this doesn't quite agree with our CSS (we need some left-hand padding):

I got this inspiration / technique from (source):
https://docs.readthedocs.org/en/latest/

As a test to see if our docs would build in the readthedocs theme, I swapped out html_theme for 'sphinx_rtd_theme' and turned off our custom html_style. The resulting output is a mess (I think our custom template is to blame):

@tseaver I fixed the failure (was really just #1029 showing) and rebased against master. The merging of #1026 makes this "ready to go" for activating RTD.

I jumped the gun on getting it up on RTD, looks pretty silly 😄

@tseaver and @jgeewax, what are your readthedocs.org usernames so I can add you as admins of the project?

Mine is tseaver.

@tseaver Added you as a maintainer. Are you reviewing this?

@tseaver Any issues with these changes?

Sorry, I thought from the botched rendering in the last example it wasn't ready to go. LGTM.

@tseaver Do you know much about RTD?

It's using the old Sphinx theme for some reason (though not locally via LOCAL_RTD=True tox -e docs):
http://gcloud-python.readthedocs.org/en/latest/

I think it might be my use of

if ON_READ_THE_DOCS or LOCAL_READ_THE_DOCS:
  templates_path = []
else:
  templates_path = ['_templates']

i.e. I think RTD uses _templates.

Scratch that, it was the use of html_theme = 'classic', which gets picked up by us here on RTD.