Re: typedef output question/issue?

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

On Thu, 21 Nov 2024, Jani Nikula <jani.nikula@linux.intel.com> wrote:
> 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.

*ambiguous, obvs!

>
>> 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