Using caption with different toc sections instead of JS/CSS hack.

[dhermes]

Using caption with different toc sections instead of JS/CSS hack.

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

---

Building with tox -e docs we get:

---

Building with LOCAL_RTD=True tox -e docs we get:

AFAICT, by using :titlesonly: and some other rules we can get rid of the expandable sections (or just not use h1, or change maxdepth).

[dhermes]

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

[dhermes]

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):

[dhermes]

@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.

[dhermes]

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?

[tseaver]

Mine is tseaver.

[dhermes]

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

[dhermes]

@tseaver Any issues with these changes?

[tseaver]

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

[dhermes]

@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/

[dhermes]

I think it might be my use of

ifON_READ_THE_DOCSorLOCAL_READ_THE_DOCS:
templates_path= []
else:
templates_path= ['_templates']

i.e. I think RTD uses _templates.

[dhermes]

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