[PATCH] doc: add eal_args.include to toctree

[PATCH] doc: add eal_args.include to toctree

[Kevin Traynor]

A warning is observed on RHEL 8.4.

[1/1] Generating html_guides with a custom command
/root/dpdk/doc/guides/linux_gsg/eal_args.include.rst:
WARNING: document isn't included in any toctree

Add file to toctree to remove warning.

Fixes: 3ee567cfec37 ("doc: document all EAL parameters in one place")
Cc: stable@dpdk.org

Signed-off-by: Kevin Traynor <ktraynor@redhat.com>
---
 doc/guides/linux_gsg/index.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/doc/guides/linux_gsg/index.rst b/doc/guides/linux_gsg/index.rst
index 16a9a67260..cffa4998d8 100644
--- a/doc/guides/linux_gsg/index.rst
+++ b/doc/guides/linux_gsg/index.rst
@@ -17,4 +17,5 @@ Getting Started Guide for Linux
     linux_drivers
     build_sample_apps
+    eal_args.include
     linux_eal_parameters
     enable_func
-- 
2.34.1

Re: [PATCH] doc: add eal_args.include to toctree

[Bruce Richardson]

On Thu, Mar 31, 2022 at 02:26:54PM +0100, Kevin Traynor wrote:
> A warning is observed on RHEL 8.4.
> 
> [1/1] Generating html_guides with a custom command
> /root/dpdk/doc/guides/linux_gsg/eal_args.include.rst:
> WARNING: document isn't included in any toctree
> 
> Add file to toctree to remove warning.
> 
> Fixes: 3ee567cfec37 ("doc: document all EAL parameters in one place")
> Cc: stable@dpdk.org
> 
> Signed-off-by: Kevin Traynor <ktraynor@redhat.com>
> ---
>  doc/guides/linux_gsg/index.rst | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/doc/guides/linux_gsg/index.rst b/doc/guides/linux_gsg/index.rst
> index 16a9a67260..cffa4998d8 100644
> --- a/doc/guides/linux_gsg/index.rst
> +++ b/doc/guides/linux_gsg/index.rst
> @@ -17,4 +17,5 @@ Getting Started Guide for Linux
>      linux_drivers
>      build_sample_apps
> +    eal_args.include
>      linux_eal_parameters
>      enable_func

I think this is a false-positive warning, that shouldn't be fixed in this
way. That file is not one to be put at the top level of the doc - instead
it is included by both freesd and linux gsg guides within the relevant
sections. If we can't suppress this warning, maybe we need to rename the
file to not end with a .rst extension.

/Bruce

Re: [PATCH] doc: add eal_args.include to toctree

[Kevin Traynor]

On 31/03/2022 14:51, Bruce Richardson wrote:
> On Thu, Mar 31, 2022 at 02:26:54PM +0100, Kevin Traynor wrote:
>> A warning is observed on RHEL 8.4.
>>
>> [1/1] Generating html_guides with a custom command
>> /root/dpdk/doc/guides/linux_gsg/eal_args.include.rst:
>> WARNING: document isn't included in any toctree
>>
>> Add file to toctree to remove warning.
>>
>> Fixes: 3ee567cfec37 ("doc: document all EAL parameters in one place")
>> Cc: stable@dpdk.org
>>
>> Signed-off-by: Kevin Traynor <ktraynor@redhat.com>
>> ---
>>   doc/guides/linux_gsg/index.rst | 1 +
>>   1 file changed, 1 insertion(+)
>>
>> diff --git a/doc/guides/linux_gsg/index.rst b/doc/guides/linux_gsg/index.rst
>> index 16a9a67260..cffa4998d8 100644
>> --- a/doc/guides/linux_gsg/index.rst
>> +++ b/doc/guides/linux_gsg/index.rst
>> @@ -17,4 +17,5 @@ Getting Started Guide for Linux
>>       linux_drivers
>>       build_sample_apps
>> +    eal_args.include
>>       linux_eal_parameters
>>       enable_func
> 
> I think this is a false-positive warning, that shouldn't be fixed in this
> way. That file is not one to be put at the top level of the doc - instead
> it is included by both freesd and linux gsg guides within the relevant
> sections. If we can't suppress this warning, maybe we need to rename the
> file to not end with a .rst extension.
> 

Ok, it's not a big deal anyway, RHEL 8.4 is using an old version of 
sphinx (1.7.6). I can't reproduce on Fedora with a newer version (3.4.3) 
and no one else seems to see it.

I tried to remove the warning with :orphan: but I'm not sure it's that 
well supported in that version. Removing the .rst doesn't seem like the 
right thing either. I'm ok to live with the warning on older sphinx. 
Thanks for replying.

Kevin.

> /Bruce
>