[Boost-gil] Section anchors and inter-section links

Subject: [Boost-gil] Section anchors and inter-section links
From: Stefan Seefeld (stefan_at_[hidden])
Date: 2018-04-06 13:47:05

[Following up this discussion on the list.]

On 04.04.2018 12:30, Mateusz Loskot wrote:
> On 4 April 2018 at 17:33, Stefan Seefeld <stefan_at_[hidden]
> <mailto:stefan_at_[hidden]>> wrote:
>
>     On 04.04.2018 09:49, Mateusz Loskot wrote:
>>     On 4 April 2018 at 13:50, Stefan Seefeld <stefan_at_[hidden]
>>     <mailto:stefan_at_[hidden]>> wrote:
>>
>>
>>
>>         It seems the mechanism we want is
>>         http://www.sphinx-doc.org/en/stable/ext/autosectionlabel.html
>>         <http://www.sphinx-doc.org/en/stable/ext/autosectionlabel.html>
>>
>>
>>
>>     Do you mind if we enable and use it?
>
>     Looking into it.
>     (I enabled it and now get warnings, as certain section titles
>     appear multiple times, even in the same document: e.g. "related",
>     "models". I need to think how to handle that.)
>
>
> Thank you!
>
> Let me know if you need help.

I still haven't acted upon this. The code of the extension is rather
trivial
(https://github.com/sphinx-doc/sphinx/blob/master/sphinx/ext/autosectionlabel.py#L32-L52).
The `design_guide.rst` document contains multiple (sub-)sections called
"Models" (as well as "Related Concepts"), which cause warnings. Here are
a few ways to deal with this:

1) ignore the warnings (and not use references to those sub-sections)
2) not use the auto-labeling feature, and instead insert explicit
anchors
(http://www.sphinx-doc.org/en/stable/markup/inline.html#cross-referencing-arbitrary-locations)
3) clone the `autosectionlabel` extension and adjust it to ignore those
duplicate sections

I'm somewhat split between option 1) and 2). If we think we use section
references relatively rarely, option 2) may be better. 1) is certainly
the most convenient, but having to live with warnings is certainly less
clean than dealing with the issue somehow.
In any case, I think I'm going to change the "Related Concepts"
sections, so they no longer are sections, but some other construct (such
as
http://www.sphinx-doc.org/en/stable/markup/para.html?highlight=seealso#directive-seealso),
which should cut the number of warnings approximately in half.

Thoughts ?

Stefan

-- 
      ...ich hab' noch einen Koffer in Berlin...