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

Subject: Re: [Boost-gil] Section anchors and inter-section links
From: Stefan Seefeld (stefan_at_[hidden])
Date: 2018-04-06 14:45:44

On 06.04.2018 10:37, Mateusz Loskot wrote:
> 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.

Oh, good point ! We may restructure the documentation, so this may no
longer be an issue. OK, one more reason to go with the simplest solution
for now. I'll thus enable the auto-label generation, and then we can
revisit this once we talk about documentation refactorization..

Thanks,

Stefan

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