On Thu, 21 Nov 2024, Randy Dunlap <rdunlap@xxxxxxxxxxxxx> wrote: > On 11/21/24 3:19 AM, Jani Nikula wrote: >> On Thu, 21 Nov 2024, Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> wrote: >>> On Wed, 20 Nov 2024, Randy Dunlap <rdunlap@xxxxxxxxxxxxx> 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! > > Sorry about that. I would like to see 'typedef' instead of 'type'. Right, so looking into it, Sphinx actually has two forms for documenting types, described at [1]: .. c:type:: foo_t .. c:type:: int foo_t The former is simple, and becomes a generic "type" in rendered documentation, while the latter can contain a "typedef-like declaration", and becomes "typedef" in rendered documentation. So, if you can make kernel-doc emit a proper typedef for the c:type directive, the output will contain typedef, but otherwise remains just type. Whether having the actual typedef declaration in the output is something you also want, is a different matter. The man page output doesn't go through Sphinx at all, and is just whatever kernel-doc outputs. HTH, Jani. [1] https://www.sphinx-doc.org/en/master/usage/domains/c.html#directive-c-type > > Thanks. > >> >>> >>>> 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? > > One function or identifier (struct, union, enum, or typedef) at a time. > Just for testing. > > $ scripts/kernel-doc -man -function function_or_identifier file | nroff -man | less > > e.g.: > $ scripts/kernel-doc -man -function dma_cookie_t include/linux/dmaengine.h | nroff -man | less > >>> >>>> 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. >>> > > OK, thanks. I'll just try to ignore it. :( > >>> >>> 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
