Re: Functions and data structure cross references with Sphinx

[Mauro Carvalho Chehab <mchehab@s-opensource.com>]

Em Fri, 5 Aug 2016 14:22:19 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> Am 05.08.2016 um 12:47 schrieb Mauro Carvalho Chehab <mchehab@s-opensource.com>:
> 
> > Em Fri, 5 Aug 2016 09:29:23 +0200
> > Markus Heiser <markus.heiser@darmarit.de> escreveu:
> >   

> > Is there a way for us to specify the nitpick_ignore list (or a different
> > conf.py) via command line?  
> 
> Since conf.py is python, we could implement something, which loads a
> "conditional configuration", e.g. loading a config with a nitpick_ignore
> list in. Depending on an environment 
> 
>  "SPHINX_BUILD_CONF=[strong|lazy]-nit-picking.py"
> 
> we could load individual build-configs overwriting the default settings
> from the origin conf.py.

That would be interesting!

> On which repo/branch you are working? .. I send you a RFC patch 
> for "conditional configurations".

You can send it against either the media_tree.git[1] or the upstream 
one[2]. All Sphinx patches I have were merged there already (except for 
the experimental nickpick patch I attached on the previous e-mail).

[1] https://git.linuxtv.org/media_tree.git/log/
[2] https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/

> > 3) The references generated from the header files I'm parsing don't
> > use the c (or cpp) domain. They're declared at the media book as a
> > normal reference:
> > 	Documentation/media/uapi/v4l/field-order.rst:.. _v4l2-field:
> > 

> Back to (3) ... as far as I know, there is no way to add a 
> *Internal Hyperlink Target* (e.g. "_v4l2-field:") to the C or 
> CPP domain.

Argh!

> 
> There is a ":any:" directive does something vice versa.
> 
> http://www.sphinx-doc.org/en/stable/markup/inline.html#role-any
> 
> But I think, this will not help referencing a type from a function
> prototype to a *Internal Hyperlink Target*, like the struct described
> under the "_v4l2-field:" target.

Hmm... it might help, but this is Sphinx 1.3 or upper only.
As we decide to set the minimal version bar to 1.2, we should
avoid using it.

> 
> If ":any:" does not help, we might find a solution with an additional
> crossref-type or something similar:
> 
> http://www.sphinx-doc.org/en/stable/extdev/appapi.html#sphinx.application.Sphinx.add_crossref_type
> 
> But this needs some more thoughts.

That sounds more promising, but we'll need a replacement for the
:c:func: tag to use it.


Thanks,
Mauro