[pbs-devel] [PATCH proxmox-backup 2/2] docs/scanrefs: fix handling if ref is same as headline

[Thomas Lamprecht]

On 05.02.21 16:10, Aaron Lauterer wrote:
> If the ref is named the same as the headline (once normalized), sphinx
> will return a 'idX' value in node['ids'][1] which we use for the label
> ID. The headline is always present at index 0.
> 
> Checking for that and using index 0 in case we do get a 'idX' helps us
> to avoid using the 'idX' as keys in our OnlineHelpInfo.js and actually
> use the intended key.
> 
> Signed-off-by: Aaron Lauterer <a.lauterer at proxmox.com>
> ---
>  docs/_ext/proxmox-scanrefs.py | 13 ++++++++++++-
>  1 file changed, 12 insertions(+), 1 deletion(-)
> 
> diff --git a/docs/_ext/proxmox-scanrefs.py b/docs/_ext/proxmox-scanrefs.py
> index 1b3c0615..0d626561 100644
> --- a/docs/_ext/proxmox-scanrefs.py
> +++ b/docs/_ext/proxmox-scanrefs.py
> @@ -90,7 +90,18 @@ class ReflabelMapper(Builder):
>                  if hasattr(node, 'expect_referenced_by_id') and len(node['ids']) > 1: # explicit labels
>                      filename = self.env.doc2path(docname)
>                      filename_html = re.sub('.rst', '.html', filename)
> -                    labelid = node['ids'][1] # [0] is predefined by sphinx, we need [1] for explicit ones
> +
> +                    # node['ids'][0] contains a normalized version of the
> +                    # headline.  If the ref and headline are the same
> +                    # (normalized) sphinx will set the node['ids'][1] to a
> +                    # generic id in the format `idX` where X is numeric. If the
> +                    # ref and headline are not the same, the ref name will be
> +                    # stored in node['ids'][1]

can you point me from where you derived that?

Because I think there are always two refs in such cases where we set one
above a heading: the implicit heading one and the explicit from us.
The always get normalized, but the implicit has a fallback if there's a ref
conflict with an explicit or even another implicit one, when a title is
reused in the same chapter or so?

Do we also have access to the chapter id/name here?
Then we could enforce that explicit ones must have that prefixed.

> +                    if re.match('^id[0-9]*$', node['ids'][1]):

should be a + not * op? we want to avoid clashes with real possible refs
as much as possible..

What happens if I set now one to id1 and there would be already an id1?

I just really do not want to revisit this again, and loosing references
is a no-go, the docs must work.

> +                        labelid = node['ids'][0]
> +                    else:
> +                        labelid = node['ids'][1]
> +
>                      title = cast(nodes.title, node[0])
>                      logger.info('traversing section {}'.format(title.astext()))
>                      ref_name = getattr(title, 'rawsource', title.astext())
>