On 07/11/2023 02:41, Jani Nikula wrote: > On Mon, 06 Nov 2023, Hunter Chasens <hunter.chasens18@xxxxxxx> wrote: >> When running `make htmldocs` the following warnings are given. >> >> ``` >> Documentation/gpu/rfc/i915_scheduler.rst:138: WARNING: >> Unknown directive type "c:namespace-push". >> >> .. c:namespace-push:: rfc >> Documentation/gpu/rfc/i915_scheduler.rst:143: WARNING: >> Unknown directive type "c:namespace-pop". >> >> .. c:namespace-pop:: >> ``` >> >> The kernel test robot also reported it here. >> Link: https://lore.kernel.org/all/202311061623.86pTQrie-lkp@xxxxxxxxx/ >> >> Last year Maryam Tahhan <mtahhan@xxxxxxxxxx> from Redhat noticed something >> similar. "The missing support of c:namespace-push:: and c:namespace-pop:: >> directives by helper scripts for kernel documentation prevents using the >> ``c:function::`` directive with proper namespacing." From the context, it >> sounds like this was brought about from a Sphinx update. >> >> Link: https://lore.kernel.org/all/20221123092321.88558-3-mtahhan@xxxxxxxxxx/ >> >> When compiled the `.. kernel-doc::` literal gives it the same formatting with >> or without the namespace directives present. Due to the above information I >> think it safe to remove these, as they don't seem to do anything but >> throw warnings. > > Not so fast! > > Looks like this is because namespacing was introduced in Sphinx 3.1 > [1]. With earlier Sphinx, you get a warning about the namespace > directives. > > However, with newer Sphinx, you get the warning mentioned in commit > f6757dfcfde7 ("drm/doc: fix duplicate declaration warning") if you > remove the namespace directives: > > linux/Documentation/gpu/driver-uapi.rst:2279: WARNING: Duplicate C declaration, also defined at rfc/i915_scheduler:3. > Declaration is '.. c:struct:: i915_context_engines_parallel_submit'. > > It would be short-sighted to just remove the directives. Sooner or later > we're gong to bump the (IMO extremely conservative) minimum version > requirement. > OK, thanks for explanation! -- An old man doll... just what I always wanted! - Clara
