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

[Bird, Tim]

OK.  I have enabled this in docs/rst_src/conf.py for Fuego.

I had to upgrade my version of sphinx.  I'm now using a python virtual environment
for my doc builds, and I put some notes in docs/NOTES-using-sphinx.txt

This virtual environment may only be needed if a user is trying to build
the docs on an old Linux distribution. (I'm using Ubuntu 16.04, and the distro-provided
sphinx package is pretty old.)

Anyway, this should be a nice solution to the problem of having to create
a lot of anchors everywhere.

Thanks,
 -- Tim


> -----Original Message-----
> From: Pooja Sanjay More
> Hi,
> 
> Regarding conventions for anchor labels, we can use the "sphinx.ext.autosectionlabel" configuration variable to auto generate labels for
> headings.
> By enabling it, we can directly use the title of the page to cross reference instead of anchor label.
> 
> The limitation of using the above configuration is that -- there should not be any duplicate headings.
> The page titles should be unique throughout the documentation.
> 
> I have tried to use the same and it's working fine.
> 
> 
> On Tue, Sep 22, 2020 at 10:01 AM Bird, Tim <Tim.Bird at sony.com <mailto:Tim.Bird at sony.com> > wrote:
> 
> 
> 	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
> 
> 
> 
> 
> This message contains confidential information and is intended only for the individual(s) named. If you are not the intended recipient, you
> are notified that disclosing, copying, distributing or taking any action in reliance on the contents of this mail and attached file/s is strictly
> prohibited. Please notify the sender immediately and delete this e-mail from your system. E-mail transmission cannot be guaranteed to be
> secured or error-free as information could be intercepted, corrupted, lost, destroyed, arrive late or incomplete, or contain viruses. The
> sender therefore does not accept liability for any errors or omissions in the contents of this message, which arise as a result of e-mail
> transmission.