Re: [Fuego] RST link painfulness - (was RE: Fwd: RST_Docs conversion)

I forgot to mention that I did all this work in the master branch, and
pushed it.  So the repository on bitbucket should be up-to-date (but
I haven't integrated your 2nd two patches yet).
 -- Tim


> -----Original Message-----
> From: Bird, Tim
> Sent: Monday, September 21, 2020 10:31 PM
> To: Pooja Sanjay More <[email protected]>; [email protected]
> Cc: Srivatsan S <[email protected]>
> Subject: RST link painfulness - (was RE: [Fuego] Fwd: RST_Docs conversion)
> 
> Pooja,
> 
> 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.
> 
> Thanks,
>  -- Tim