Re: typedef output question/issue?

[Jani Nikula <jani.nikula@linux.intel.com>]

On Wed, 20 Nov 2024, Randy Dunlap <rdunlap@infradead.org> wrote:
> Hi,
>
> If I print a typedef in html (make htmldocs) from a .rst file,
> I see:
>
> type dma_cookie_t
>     an opaque DMA cookie
>
> Description
>
> if dma_cookie_t is >0 it’s a DMA request cookie, <0 it’s an error code
>
> ~~~~~~~~~~~~~~~~~~~
>
> If I print the same typedef in man format, it says 'typedef' instead of
> 'type', which is what I expect to see.

I'm sorry, it's unambigous to me which one you expect.

> man formatted output:
>
> Kernel API(9)                     API Manual                     Kernel API(9)
>
> NAME
>        typedef dma_cookie_t - an opaque DMA cookie
>
> Description
>        if dma_cookie_t is >0 it's a DMA request cookie, <0 it's an error code
>
> November 2024                    dma_cookie_t                    Kernel API(9)

How do you generate the man pages?

> I am using python311-Sphinx 8.0.2-1.2-noarch from openSUSE.
>
> [internet search ...]
>
> The $internet says that one option is to install and use:
> Add 'sphinx_autodoc_typehints' to the extensions list in your conf.py file.
> I tried that but now I get:
> Extension error:
> Unknown event name: autodoc-process-signature

The kernel-doc thing is not hooked up in the Sphinx autodoc processing,
which is more geared towards Python. I presume sphinx_autodoc_typehints
uses autodoc-process-signature which isn't there because the autodoc
Sphinx extension isn't loaded, and even if it were, would not be called
on kernel-doc handling.


BR,
Jani.


>
> Another option is to try a different theme so I reverted to
> sphinx_rtd_theme but that didn't help either.
>
> Does anyone know a good solution to this?
>
> thanks.

-- 
Jani Nikula, Intel