Question for Sphinx experts

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?

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

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.

https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html?highlight=…%20option#directive-program might be what you are looking for. You probably need multiple program directives (llvm-tblgen, mlir-tblgen etc), since it sounds to me like you are dealing with multiple different (albeit related) programs, since the same program can’t have two identically-named but different options.