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

Subject: Re: [Boost-gil] Section anchors and inter-section links
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2018-04-06 14:37:23

On 6 April 2018 at 15:47, Stefan Seefeld <stefan_at_[hidden]> wrote:
> 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
>>>
>>>     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.)
>
> 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).

I guess, technically feasible solution may be splitting the large
design_guide.rst into design/point.rst, design/channel.rst, etc.

Otherwise, I'm fine with either 1) or 2), at least for the grand merge.

Best regards,
-- 
Mateusz Loskot, http://mateusz.loskot.net