Re: Functions and data structure cross references with Sphinx

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Am 01.08.2016 um 13:25 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>:

> There's one remaining major issue I noticed after the conversion of the
> media books to Sphinx:
> 
> While sphinx complains if a cross-reference (using :ref:) points to an
> undefined reference, the same doesn't happen if the reference uses
> :c:func: and :c:type:.
> 
> In practice, it means that, if we do some typo there, or if we forget to
> add the function/struct prototype (or use the wrong domain, like :cpp:),
> Sphinx won't generate the proper cross-reference, nor warning the user.
> 
> That's specially bad for media, as, while we're using the c domain for
> the kAPI and driver-specific books, we need to use the cpp domain on the 
> uAPI book - as the c domain doesn't allow multiple declarations for
> syscalls, and we have multiple pages for read, write, open, close, 
> poll and ioctl.
> 
> It would be good to have a way to run Sphinx on some "pedantic"
> mode or have something similar to xmlint that would be complaining
> about invalid c/cpp domain references.
> 
> Thanks,
> Mauro

Hi Mauro,

there is a nit-picky mode [1], which could be activated by setting
"nitpicky=True" in the conf.py or alternative, set "-n" to the 
SPHINXOPTS:

  make SPHINXOPTS=-n htmldocs

Within nit-picky mode, Sphinx will warn about **all** references. This
might be more then you want. For this, in the conf.py you could
assemble a "nitpick_ignore" list [2]. But I think, assemble the
ignore list is quite a lot of work.

[1] http://www.sphinx-doc.org/en/stable/config.html#confval-nitpicky
[2] http://www.sphinx-doc.org/en/stable/config.html#confval-nitpick_ignore

-- Markus ----
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html



[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux