Re: [PATCH v4] doc/sphinx/hxtool.py: add optional label argument to SRST directive

[Peter Maydell <peter.maydell@linaro.org>]

On Tue, 30 Jan 2024 at 19:04, David Woodhouse <dwmw2@infradead.org> wrote:
>
> From: David Woodhouse <dwmw@amazon.co.uk>
>
> We can't just embed labels directly into files like qemu-options.hx which
> are included from multiple top-level rST files, because Sphinx sees the
> labels as duplicate: https://github.com/sphinx-doc/sphinx/issues/9707
>
> So add an optional argument to the SRST directive which causes a label
> of the form '.. _DOCNAME-HXFILE-LABEL:' to be emitted, where 'DOCNAME'
> is the name of the top level rST file, 'HXFILE' is the filename of the
> .hx file, and 'LABEL' is the text provided within the 'SRST()' directive.
> Using the DOCNAME of the top-level rST document means that it is unique
> even when the .hx file is included from two different documents, as is
> the case for qemu-options.hx
>
> Now where the Xen PV documentation refers to the documentation for the
> -initrd command line option, it can emit a link directly to it as
> '<system/invocation-qemu-options-initrd>'.
>
> Signed-off-by: David Woodhouse <dwmw@amazon.co.uk>
> Reviewed-by: Paul Durrant <paul@xen.org>
> Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
> ---
> v4:
>  • Wrap long lines to shut checkpatch up

Applied to target-arm.next, thanks.

PS: for checkpatch long lines, note that our coding style doc
permits line lengths which checkpatch will warn about, if
it would be "obviously less readable" than wrapping. So
that particular warning is more of a "look at this and see
if it could be written in a different way" rather than a
"definitely change this to get rid of the warning" one.

(At some point I might try to go back and get the discrepancy
between what our coding style doc says checkpatch complains
about and what it actually complains about straightened out.
The underlying issue is that there's no consensus between
whether it's better that:
 * checkpatch produces a warning on code that's in a "grey
   area" where we might be OK with it but it might be better
   to change it, so that the patch submitter is prompted to
   look at that part of the change and consider altering it
 * checkpatch doesn't warn about "grey area" situations,
   so that we don't have "checkpatch complains but we're
   actually happy with the patch and wouldn't want it changed"
   situations
)

-- PMM