[cfe-dev] Clang Sphinx Attribute doc broken

[Aaron Ballman via cfe-dev]

On Thu, Jan 26, 2017 at 1:43 AM, Tanya Lattner <tanyalattner at llvm.org> wrote:
> There are actually a ton of warnings that I had to turn off the default of
> treating warnings as errors. I haven’t had time to start filing bug reports
> but will do so. The only thing “new” about how docs are built is that its a
> new system with new compilers and different versions of sphinx.
>
> I’ve switched the Clang Attr doc to build even with warnings.. and CC-ing
> Aaron to help fix this.

I think that this particular warning needs to be disabled as it's
basically a useless diagnostic. The sphinx option parser doesn't
handle duplicate entries very well, which we can sometimes workaround,
but not always. For instance, this is a frequent issue:

.. option:: -foo, -foo=bar, -foo=baz

Sphinx sees this as defining three options with the same name. We can
fix this by instead doing: .. option:: -foo=<bar|baz>

However, Sphinx has no way to handle an option like this:

.. option:: -ObjC, -ObjC++

It doesn't process that the ++ are part of the name of the option, and
so it thinks there are two options named ObjC. I can't seem to find
any way to get Sphinx to accept that as two options.

~Aaron

>
> -Tanya
>
>
> On Jan 24, 2017, at 4:22 AM, Hahnfeld, Jonas <Hahnfeld at itc.rwth-aachen.de>
> wrote:
>
> Just want to add here that LLVM has a similar problem:
> src/trunk/docs/CommandGuide/lit.rst:64: WARNING: Duplicate explicit target
> name: "cmdoption-D"
>
> This happens since sphinx-1.5, sphinx-1.4 is fine AFAICS
>
> Cheers,
> Jonas
>
> From: cfe-dev [mailto:cfe-dev-bounces at lists.llvm.org] On Behalf Of Eric
> Fiselier via cfe-dev
> Sent: Tuesday, January 24, 2017 12:05 PM
> To: clang developer list
> Cc: Tanya Lattner
> Subject: [cfe-dev] Clang Sphinx Attribute doc broken
>
> Hi all,
>
> Ever since we switch over to the new system of building documentation the
> Clang attribute doc has not been updating because each build reports an
> error.
>
> The error causing the failure is:
>
>> Warning, treated as error:
>>
>> /opt/clang_commandline_docs/src/llvm/tools/clang/docs/CommandGuide/clang.rst:122:
>> WARNING:  Duplicate explicit target name: "cmdoption-ObjC".
>
> How should we go about fixing this?
>
> /Eric
>
>