Em Fri, 20 Mar 2020 12:59:18 +0100
Mauro Carvalho Chehab [off-list ref] escreveu:

Em Fri, 20 Mar 2020 12:24:45 +0100
Federico Vaga [off-list ref] escreveu:

quoted

On Friday, March 20, 2020 12:12:35 PM CET Mauro Carvalho Chehab wrote:

quoted

The autosectionlabel extension is nice, as it allows to refer to
a section by its name without requiring any extra tag to create
a reference name.

However, on its default, it has two serious problems:

1) the namespace is global. So, two files with different
   "introduction" section would create a label with the
   same name. This is easily solvable by forcing the extension
   to prepend the file name with:

	autosectionlabel_prefix_document = True

2) It doesn't work hierarchically. So, if there are two level 1
   sessions (let's say, one labeled "open" and another one "ioctl")
   and both have a level 2 "synopsis" label, both section 2 will
   have the same identical name.

   Currently, there's no way to tell Sphinx to create an
   hierarchical reference like:

		open / synopsis
		ioctl / synopsis

  This causes around 800 warnings. So, the fix should be to
  not let autosectionlabel to produce references for anything
  that it is not at level one, with:

	autosectionlabel_maxdepth = 1  

So, for level 1 headers is fine to use autosectionlabel, but if we want to 
refer to level 2,3... we have to create labels manually.

Yes.

Hmm... actually no. maxdepth = 1 will only get the title of each
document.

It should be at least maxdepth = 2, but this is producing some warnings
here (part on some new patches I wrote, that aren't upstream yet).

I'll run some tests and send a new version of this patch.

If we want to use it for other levels, the autosectionlabel extension
would need to be modified to work on an hierarchical way, creating an
unique label that would contain the entire hierarchy, starting from
the filename.

Also, ideally, it should also handle cross-reference locally, searching
first for a reference at the same hierarchical level, then at level - 1
and so on.

I suspect that, even with that, we may still have some troubles, as
right now some files may have explicitly defined a reference like
that, but those would likely be easy to fix.

Thanks,
Mauro

Thanks,
Mauro