| Message ID | 20231108152727.58764-4-andrew.cooper3@citrix.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | docs/sphinx: Fix syntax errors and warnings | expand |
Hi, > On Nov 8, 2023, at 23:27, Andrew Cooper <andrew.cooper3@citrix.com> 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@citrix.com> Release-acked-by: Henry Wang <Henry.Wang@arm.com> Kind regards, Henry
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@citrix.com> > > --- > CC: George Dunlap <George.Dunlap@citrix.com> > CC: Jan Beulich <JBeulich@suse.com> > CC: Stefano Stabellini <sstabellini@kernel.org> > CC: Wei Liu <wl@xen.org> > CC: Julien Grall <julien@xen.org> > CC: Henry Wang <Henry.Wang@arm.com> > --- > 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 >
On 10/11/2023 12:07 am, Stefano Stabellini wrote: > On Wed, 8 Nov 2023, Andrew Cooper wrote: >> 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? You can't have it both here and in index.rst without breaking the indexing. Also because in it's current position it breaks the navbar. MISRA is part of the developer guide, and what should be at the toplevel should be a general section on safety certification, which cross-references the developer guide amongst other things. Nevertheless it will stay visible for now at the top level because of how the toctree. It's in unsorted because I have thrown the index together with the bare minimum effort in order to fix Sphinx errors in time for 4.18. This is also why I'm not changing any text. There is 0 time between now and this needing fixing for the release. Someone else can find some time to polish it - which is far more work than just in the index - and we can backport it when its done. ~Andrew
On Fri, 10 Nov 2023, Andrew Cooper wrote: > On 10/11/2023 12:07 am, Stefano Stabellini wrote: > > On Wed, 8 Nov 2023, Andrew Cooper wrote: > >> 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? > > You can't have it both here and in index.rst without breaking the indexing. > > Also because in it's current position it breaks the navbar. MISRA is > part of the developer guide, and what should be at the toplevel should > be a general section on safety certification, which cross-references the > developer guide amongst other things. Nevertheless it will stay visible > for now at the top level because of how the toctree. > > It's in unsorted because I have thrown the index together with the bare > minimum effort in order to fix Sphinx errors in time for 4.18. > > This is also why I'm not changing any text. There is 0 time between now > and this needing fixing for the release. > > Someone else can find some time to polish it - which is far more work > than just in the index - and we can backport it when its done. OK. I don't mean to make things difficult so if you don't think it is easy to keep "MISRA C coding guidelines" here in docs/index.rst then so be it. Can you at least add "and related files" to the text in docs/misra/index.rst? Can be done on commit. Anyway: Acked-by: Stefano Stabellini <sstabellini@kernel.org>
On 10/11/2023 11:49 pm, Stefano Stabellini wrote: > On Fri, 10 Nov 2023, Andrew Cooper wrote: >> On 10/11/2023 12:07 am, Stefano Stabellini wrote: >>> On Wed, 8 Nov 2023, Andrew Cooper wrote: >>>> 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? >> You can't have it both here and in index.rst without breaking the indexing. >> >> Also because in it's current position it breaks the navbar. MISRA is >> part of the developer guide, and what should be at the toplevel should >> be a general section on safety certification, which cross-references the >> developer guide amongst other things. Nevertheless it will stay visible >> for now at the top level because of how the toctree. >> >> It's in unsorted because I have thrown the index together with the bare >> minimum effort in order to fix Sphinx errors in time for 4.18. >> >> This is also why I'm not changing any text. There is 0 time between now >> and this needing fixing for the release. >> >> Someone else can find some time to polish it - which is far more work >> than just in the index - and we can backport it when its done. > OK. I don't mean to make things difficult so if you don't think it is > easy to keep "MISRA C coding guidelines" here in docs/index.rst then so > be it. Can you at least add "and related files" to the text in > docs/misra/index.rst? Ok. > Can be done on commit. Anyway: > > Acked-by: Stefano Stabellini <sstabellini@kernel.org> Thanks. ~Andrew
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. .. 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. + +.. toctree:: + :maxdepth: 2 + + rules + deviations + C-language-toolchain + C-runtime-failures + documenting-violations + exclude-list + xen-static-analysis
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@citrix.com> --- CC: George Dunlap <George.Dunlap@citrix.com> CC: Jan Beulich <JBeulich@suse.com> CC: Stefano Stabellini <sstabellini@kernel.org> CC: Wei Liu <wl@xen.org> CC: Julien Grall <julien@xen.org> CC: Henry Wang <Henry.Wang@arm.com> --- docs/index.rst | 13 +++++++------ docs/misra/index.rst | 18 ++++++++++++++++++ 2 files changed, 25 insertions(+), 6 deletions(-) create mode 100644 docs/misra/index.rst