Removed unused directives for namespacing I believe to have been
originally introduced as a workaround for a Sphinx warning.
Signed-off-by: Hunter Chasens <[email protected]>
---
Documentation/gpu/rfc/i915_scheduler.rst | 4 ----
1 file changed, 4 deletions(-)
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::
-
Extend execbuf2 IOCTL to support submitting N BBs in a single IOCTL
-------------------------------------------------------------------
Contexts that have been configured with the 'set_parallel' extension can only
--
2.39.3
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::
> -
> 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!
Fixes: f6757dfcfde7 ("drm/doc: fix duplicate declaration warning")
Reviewed-by: Bagas Sanjaya <[email protected]>
--
An old man doll... just what I always wanted! - Clara
On Mon, 06 Nov 2023, Bagas Sanjaya <[email protected]> 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 <[email protected]>
--
Jani Nikula, Intel
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/[email protected]/
Last year Maryam Tahhan <[email protected]> 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/[email protected]/
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.
On Mon, Nov 6, 2023 at 5:31 AM Jani Nikula <[email protected]> wrote:
>
> On Mon, 06 Nov 2023, Bagas Sanjaya <[email protected]> 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 <[email protected]>
>
> --
> Jani Nikula, Intel
On Mon, 06 Nov 2023, Hunter Chasens <[email protected]> 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/[email protected]/
>
> Last year Maryam Tahhan <[email protected]> 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/[email protected]/
>
> 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 <[email protected]> wrote:
>>
>> On Mon, 06 Nov 2023, Bagas Sanjaya <[email protected]> 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 <[email protected]>
>>
>> --
>> Jani Nikula, Intel
--
Jani Nikula, Intel
Jani Nikula <[email protected]> writes:
> 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.
I'd say let's just do that once the merge window is done. A year ago
(in 31abfdda6527) I added a warning for <2.4.x, so raising the minimum
that far would appear to require no thought. Going up to 3.1 is a step
beyond that, though, not sure if we want to go that far.
Something to ask at the LPC session next week.
Thanks,
jon
On 06/11/2023 17:31, Jani Nikula wrote:
> On Mon, 06 Nov 2023, Bagas Sanjaya <[email protected]> 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?
>
Oops, I mean the patch author had silenced these warnings.
--
An old man doll... just what I always wanted! - Clara
On 07/11/2023 02:41, Jani Nikula wrote:
> On Mon, 06 Nov 2023, Hunter Chasens <[email protected]> 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/[email protected]/
>>
>> Last year Maryam Tahhan <[email protected]> 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/[email protected]/
>>
>> 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