llvm dev - Jan 2021 - Question for Sphinx experts

I think you need to scope the doc - there are similar issues in various of
the LLVM binutils tools. For example, both the llvm-readelf and
llvm-objdump docs describe the `--file-headers` options. The scoping you
need (I think) is the line at the top of these docs that looks something
like `.. program:: llvm-objdump`. Indeed, without that scoping, you can
potentially end up with docs linking to options described on other pages,
which is almost certainly not what you want.

(I'm not a Sphinx expert, but did help get the LLVM binutils docs to where
they are, and I think you're describing the problem this action solved)

James

On Mon, 25 Jan 2021 at 18:15, Paul C. Anagnostopoulos via llvm-dev <
llvm-dev at lists.llvm.org> wrote:
> In the Tablegen xxx-tblgen command documentation, the following lines
> appear:
>
>   .. option:: -gen-directive-decl
>
> in the llvm-tblgen command option list, and
>
> .. option:: -gen-directive-decl
>
> in the mlir-tblgen command option list.
>
> They both generate the same target name, resulting in the warning:
>
> ...CommandGuide/tblgen.rst:589:Duplicate explicit target name:
> "cmdoption-tblgen-gen-directive-decl".
>
> The warning messes you up if you're building with warnings treated as
> errors. Does anyone know how to fix this?
>
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20210126/243af718/attachment.html>

The file has a '.. program:: tblgen' at the top. I think the issue is
that there are two identical '.. option' names in the same file.
Apparently each option generates a target name, two of which are the same.

Does anyone know where to find the documentation on the '.. option'
directive? I just exceeded by 10-minute limit on searching the interwebs.

At 1/26/2021 03:24 AM, James Henderson wrote:
>I think you need to scope the doc - there are similar issues in various of
the LLVM binutils tools. For example, both the llvm-readelf and llvm-objdump
docs describe the `--file-headers` options. The scoping you need (I think) is
the line at the top of these docs that looks something like `.. program::
llvm-objdump`. Indeed, without that scoping, you can potentially end up with
docs linking to options described on other pages, which is almost certainly not
what you want.