[v1] docs: gpu: rfc: i915_scheduler.rst remove unused directives for namespacing

  Removed unused directives for namespacing I believe to have been
originally introduced as a workaround for a Sphinx warning.

Signed-off-by: Hunter Chasens <hunter.chasens18@ncf.edu>
---
 Documentation/gpu/rfc/i915_scheduler.rst | 4 ----
 1 file changed, 4 deletions(-)
  

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 <bagasdotme@gmail.com>
  

On Mon, 06 Nov 2023, Bagas Sanjaya <bagasdotme@gmail.com> 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@gmail.com>
  

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@intel.com/

Last year Maryam Tahhan <mtahhan@redhat.com> 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@redhat.com/

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 <jani.nikula@intel.com> wrote:
>
> On Mon, 06 Nov 2023, Bagas Sanjaya <bagasdotme@gmail.com> 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@gmail.com>
>
> --
> Jani Nikula, Intel
  

On Mon, 06 Nov 2023, Hunter Chasens <hunter.chasens18@ncf.edu> 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@intel.com/
>
> Last year Maryam Tahhan <mtahhan@redhat.com> 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@redhat.com/
>
> 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@intel.com> wrote:
>>
>> On Mon, 06 Nov 2023, Bagas Sanjaya <bagasdotme@gmail.com> 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@gmail.com>
>>
>> --
>> Jani Nikula, Intel
  

Jani Nikula <jani.nikula@intel.com> 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 <bagasdotme@gmail.com> 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.
  

On 07/11/2023 02:41, Jani Nikula wrote:
> On Mon, 06 Nov 2023, Hunter Chasens <hunter.chasens18@ncf.edu> 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@intel.com/
>>
>> Last year Maryam Tahhan <mtahhan@redhat.com> 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@redhat.com/
>>
>> 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!