add captions to the split toctrees (#3466)
* add captions to the split toctrees
this will render the table of contents with separators in the RTD
theme. right now, the table of contents is quite confusing on
the [RTD site][] - that is because there are 3 distinct `toctree`
directives, but no `:caption:` field. instead, there are headers in
the `index.rst` but those are not parsed by RTD.
[RTD site]: https://cryptography.io/en/latest/
by moving those headers in the `:caption:` field, we keep the heading,
but it will also be shown in the left table of contents on the RTD
site.
for an example of that pattern, see the [scrapy documentation][]. they
go even further by hiding the `toctree` elements completely and adding
explanations on every section, but this is out of scope here for now.
[scrapy documentation]: https://doc.scrapy.org/en/latest/index.html
* remove spurious backtics in caption
they do not work in that field, apparently.
1 file changed