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

[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.

Thanks and regards,
Pooja More

On Tue, Sep 22, 2020 at 10:01 AM Bird, Tim <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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.linuxfoundation.org/pipermail/fuego/attachments/20200924/1c220245/attachment.html>