Re: [PATCH for-4.18 3/3] docs/sphinx: Fix indexing

[Stefano Stabellini <sstabellini@xxxxxxxxxx>]

On Wed, 8 Nov 2023, Andrew Cooper wrote:
> sphinx-build reports:
> 
>   docs/designs/launch/hyperlaunch.rst: WARNING: document isn't included in 
> any toctree
>   docs/designs/launch/hyperlaunch-devicetree.rst: WARNING: document isn't 
> included in any toctree
>   docs/misc/xen-makefiles/makefiles.rst: WARNING: document isn't included in 
> any toctree
>   docs/misra/C-language-toolchain.rst: WARNING: document isn't included in 
> any toctree
>   docs/misra/C-runtime-failures.rst: WARNING: document isn't included in any 
> toctree
>   docs/misra/documenting-violations.rst: WARNING: document isn't included in 
> any toctree
>   docs/misra/exclude-list.rst: WARNING: document isn't included in any toctree
>   docs/misra/xen-static-analysis.rst: WARNING: document isn't included in any 
> toctree
> 
> Create an up-to-date index.rst in misra/ create an "unsorted docs" section at
> the top level to contain everything else.  They can be re-filed at a later
> date.
> 
> Signed-off-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
>
> ---
> CC: George Dunlap <George.Dunlap@xxxxxxxxxx>
> CC: Jan Beulich <JBeulich@xxxxxxxx>
> CC: Stefano Stabellini <sstabellini@xxxxxxxxxx>
> CC: Wei Liu <wl@xxxxxxx>
> CC: Julien Grall <julien@xxxxxxx>
> CC: Henry Wang <Henry.Wang@xxxxxxx>
> ---
>  docs/index.rst       | 13 +++++++------
>  docs/misra/index.rst | 18 ++++++++++++++++++
>  2 files changed, 25 insertions(+), 6 deletions(-)
>  create mode 100644 docs/misra/index.rst
> 
> diff --git a/docs/index.rst b/docs/index.rst
> index f3f779f89ce5..22fdde80590c 100644
> --- a/docs/index.rst
> +++ b/docs/index.rst
> @@ -53,17 +53,18 @@ kind of development environment.
>     hypervisor-guide/index
>  
>  
> -MISRA C coding guidelines
> --------------------------
> +Unsorted documents
> +------------------
>  
> -MISRA C rules and directive to be used as coding guidelines when writing
> -Xen hypervisor code.
> +Documents in need of some rearranging.

I understand the need for an "Unsorted documents", but why taking away
"MISRA C coding guidelines" from here? Wouldn't we want:


Unsorted documents
------------------

designs/launch/hyperlaunch
designs/launch/hyperlaunch-devicetree
misc/xen-makefiles/makefiles


MISRA C coding guidelines
-------------------------

MISRA C rules and directive to be used as coding guidelines when writing
Xen hypervisor code and related files.

misra/index


>  .. toctree::
>     :maxdepth: 2
>  
> -   misra/rules
> -   misra/deviations
> +   designs/launch/hyperlaunch
> +   designs/launch/hyperlaunch-devicetree
> +   misc/xen-makefiles/makefiles
> +   misra/index
>  
>  
>  Miscellanea
> diff --git a/docs/misra/index.rst b/docs/misra/index.rst
> new file mode 100644
> index 000000000000..c59730c46d88
> --- /dev/null
> +++ b/docs/misra/index.rst
> @@ -0,0 +1,18 @@
> +.. SPDX-License-Identifier: CC-BY-4.0
> +
> +MISRA C coding guidelines
> +=========================
> +
> +MISRA C rules and directive to be used as coding guidelines when writing
> +Xen hypervisor code.

This is fine. I would expand it a bit appending "and related documents":

MISRA C rules and directive to be used as coding guidelines when writing
Xen hypervisor code and related documents.


> +.. toctree::
> +   :maxdepth: 2
> +
> +   rules
> +   deviations
> +   C-language-toolchain
> +   C-runtime-failures
> +   documenting-violations
> +   exclude-list
> +   xen-static-analysis
> -- 
> 2.30.2
>