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. BR, Jani. [1] https://www.sphinx-doc.org/en/master/usage/domains/c.html#namespacing > > On Mon, Nov 6, 2023 at 5:31 AM Jani Nikula <jani.nikula@xxxxxxxxx> wrote: >> >> On Mon, 06 Nov 2023, Bagas Sanjaya <bagasdotme@xxxxxxxxx> wrote: >> > On Sat, Nov 04, 2023 at 09:47:08AM -0400, Hunter Chasens wrote: >> >> diff --git a/Documentation/gpu/rfc/i915_scheduler.rst b/Documentation/gpu/rfc/i915_scheduler.rst >> >> index c237ebc024cd..23ba7006929b 100644 >> >> --- a/Documentation/gpu/rfc/i915_scheduler.rst >> >> +++ b/Documentation/gpu/rfc/i915_scheduler.rst >> >> @@ -135,13 +135,9 @@ Add I915_CONTEXT_ENGINES_EXT_PARALLEL_SUBMIT and >> >> drm_i915_context_engines_parallel_submit to the uAPI to implement this >> >> extension. >> >> >> >> -.. c:namespace-push:: rfc >> >> - >> >> .. kernel-doc:: include/uapi/drm/i915_drm.h >> >> :functions: i915_context_engines_parallel_submit >> >> >> >> -.. c:namespace-pop:: >> >> - >> >> What makes the namespacing unnecessary? >> >> $ git grep '.. kernel-doc:: include/uapi/drm/i915_drm.h' >> Documentation/gpu/driver-uapi.rst:.. kernel-doc:: include/uapi/drm/i915_drm.h >> Documentation/gpu/rfc/i915_scheduler.rst:.. kernel-doc:: include/uapi/drm/i915_drm.h >> >> And you get [1] and [2]. >> >> >> Extend execbuf2 IOCTL to support submitting N BBs in a single IOCTL >> >> ------------------------------------------------------------------- >> >> Contexts that have been configured with the 'set_parallel' extension can only >> > >> > The warnings go away, thanks! >> >> What warnings go away? >> >> BR, >> Jani. >> >> >> [1] https://docs.kernel.org/gpu/driver-uapi.html#c.i915_context_engines_parallel_submit >> [2] https://docs.kernel.org/gpu/rfc/i915_scheduler.html#c.rfc.i915_context_engines_parallel_submit >> >> > >> > Fixes: f6757dfcfde7 ("drm/doc: fix duplicate declaration warning") >> > Reviewed-by: Bagas Sanjaya <bagasdotme@xxxxxxxxx> >> >> -- >> Jani Nikula, Intel -- Jani Nikula, Intel
