[Fuego] RST link painfulness - (was RE: Fwd: RST_Docs conversion)
Tim.Bird at sony.com
Thu Sep 24 16:41:08 UTC 2020
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.
> -----Original Message-----
> From: Pooja Sanjay More
> Regarding conventions for anchor labels, we can use the "sphinx.ext.autosectionlabel" configuration variable to auto generate labels for
> 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:
> 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.
> -- 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
More information about the Fuego