[Fuego] RST link painfulness - (was RE: Fwd: RST_Docs conversion)
Tim.Bird at sony.com
Tue Sep 22 04:31:12 UTC 2020
I have done a bit more work on the Fuego RST docs. I was able to work through your first
patch, and I think I've made progress.
In the Fuego master repository, I have switched to the sphinx_rtd_theme (in conf.py).
This needs to be installed separately from Fuego for the docs to build properly, I think.
I re-worked the FrontPage.rst so that it now fits better as the "top" page of the
documentation (at least for the html docs).
I was going to suggest that we match the top level anchor for a page with the page
name, but I started experimenting around, and Sphinx does not work like I expect at
all. Apparently anchors in sphinx are case insensitive. I thought that section headers
were automatic anchors, but it doesn't appear you can reference them unless
you put an explicit anchor definition about the heading. We may want to come
up with a convention for how to name the anchor for a page or a heading,
as it's a bit hard to remember the different names when they're in different files.
My preference would be to use underscores between words, instead of running
the words together. Let me know if you have any thoughts about this.
Anyway, I'm trying not to make too big of a mess of things. I'll see if I can work
on the 'user' batch of files tomorrow.
More information about the Fuego