Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.32 as permitted sender) client-ip=23.128.96.32;
Message-ID: <ccf8c3df-ba3c-4546-88fb-dfd78ea974eb@gmail.com>
Date:   Tue, 7 Nov 2023 07:11:26 +0700
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
Subject: Re: [PATCH v1] docs: gpu: rfc: i915_scheduler.rst remove unused
 directives for namespacing
Content-Language: en-US
To:     Jani Nikula <jani.nikula@intel.com>,
        Hunter Chasens <hunter.chasens18@ncf.edu>
Cc:     corbet@lwn.net, Luca Coelho <luciano.coelho@intel.com>,
        airlied@gmail.com, daniel@ffwll.ch,
        maarten.lankhorst@linux.intel.com, mripard@kernel.org,
        tzimmermann@suse.de, dri-devel@lists.freedesktop.org,
        Linux Documentation <linux-doc@vger.kernel.org>,
        Linux Kernel Mailing List <linux-kernel@vger.kernel.org>
References: <20231104134708.69432-1-hunter.chasens18@ncf.edu>
 <ZUhvj2uj_PvaDxIM@debian.me> <8734xj18ck.fsf@intel.com>
 <CAFJe6O1oJnQvLVSJZP6MMXULGrX=a3SEO1X5b4xff06WhqLw_g@mail.gmail.com>
 <87edh2zn2y.fsf@intel.com>
From:   Bagas Sanjaya <bagasdotme@gmail.com>
In-Reply-To: <87edh2zn2y.fsf@intel.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

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!

-- 
An old man doll... just what I always wanted! - Clara