[PATCH 0/2] doc: include pages only once in TOC
Sphinx can only add a page once to the table of contents. Sphinx 8.1.3 issues a build warning when trying to add a page twice
Replace duplicate TOC entries by references.
Heinrich Schuchardt (2): doc: Semihosting should only be once in a TOC. doc: do not include K3 boards twice in TOC
doc/board/emulation/index.rst | 5 ++++- doc/board/ti/k3.rst | 11 +++++++---- 2 files changed, 11 insertions(+), 5 deletions(-)
Sphinx warns if a page is added to the table of contents twice. Add a reference instead.
Signed-off-by: Heinrich Schuchardt heinrich.schuchardt@canonical.com --- doc/board/emulation/index.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-)
diff --git a/doc/board/emulation/index.rst b/doc/board/emulation/index.rst index 98a0b26ad24..7d216f96a30 100644 --- a/doc/board/emulation/index.rst +++ b/doc/board/emulation/index.rst @@ -8,10 +8,13 @@ Emulation
acpi blkdev - ../../usage/semihosting qemu-arm qemu-mips qemu-ppce500 qemu-riscv qemu-x86 qemu-xtensa + +Also see + +* :doc:`../../usage/semihosting`
Sphinx writes a warning if a page is included twice in the table of contents. Use references instead.
Signed-off-by: Heinrich Schuchardt heinrich.schuchardt@canonical.com --- doc/board/ti/k3.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-)
diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst index c3513f0aee2..5d01f487622 100644 --- a/doc/board/ti/k3.rst +++ b/doc/board/ti/k3.rst @@ -32,19 +32,22 @@ K3 Based SoCs
am62ax_sk am62x_sk - ../beagle/am62x_beagleplay - ../phytec/phycore-am62x - ../toradex/verdin-am62 am62px_sk am64x_evm am65x_evm j7200_evm - ../beagle/j721e_beagleboneai64 j721e_evm j721s2_evm j722s_evm j784s4_evm
+K3 SoC based boards in other sections + +* :doc:`../beagle/am62x_beagleplay` +* :doc:`../beagle/j721e_beagleboneai64` +* :doc:`../phytec/phycore-am62x` +* :doc:`../toradex/verdin-am62` + Boot Flow Overview ------------------
On Mon, Oct 21, 2024 at 08:01:01PM +0200, Heinrich Schuchardt wrote:
Sphinx writes a warning if a page is included twice in the table of contents. Use references instead.
Signed-off-by: Heinrich Schuchardt heinrich.schuchardt@canonical.com
doc/board/ti/k3.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-)
diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst index c3513f0aee2..5d01f487622 100644 --- a/doc/board/ti/k3.rst +++ b/doc/board/ti/k3.rst @@ -32,19 +32,22 @@ K3 Based SoCs
am62ax_sk am62x_sk
- ../beagle/am62x_beagleplay
- ../phytec/phycore-am62x
- ../toradex/verdin-am62 am62px_sk am64x_evm am65x_evm j7200_evm
- ../beagle/j721e_beagleboneai64 j721e_evm j721s2_evm j722s_evm j784s4_evm
+K3 SoC based boards in other sections
+* :doc:`../beagle/am62x_beagleplay` +* :doc:`../beagle/j721e_beagleboneai64` +* :doc:`../phytec/phycore-am62x` +* :doc:`../toradex/verdin-am62`
Can we just make the changes to :doc: links be inline and keep the list sorted/ordered as-is? Or does that not read well once rendered?
On 10/21/24 20:12, Tom Rini wrote:
On Mon, Oct 21, 2024 at 08:01:01PM +0200, Heinrich Schuchardt wrote:
Sphinx writes a warning if a page is included twice in the table of contents. Use references instead.
Signed-off-by: Heinrich Schuchardt heinrich.schuchardt@canonical.com
doc/board/ti/k3.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-)
diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst index c3513f0aee2..5d01f487622 100644 --- a/doc/board/ti/k3.rst +++ b/doc/board/ti/k3.rst @@ -32,19 +32,22 @@ K3 Based SoCs
am62ax_sk am62x_sk
- ../beagle/am62x_beagleplay
- ../phytec/phycore-am62x
- ../toradex/verdin-am62 am62px_sk am64x_evm am65x_evm j7200_evm
- ../beagle/j721e_beagleboneai64 j721e_evm j721s2_evm j722s_evm j784s4_evm
+K3 SoC based boards in other sections
+* :doc:`../beagle/am62x_beagleplay` +* :doc:`../beagle/j721e_beagleboneai64` +* :doc:`../phytec/phycore-am62x` +* :doc:`../toradex/verdin-am62`
Can we just make the changes to :doc: links be inline and keep the list sorted/ordered as-is? Or does that not read well once rendered?
This is nothing Sphinx would understand:
WARNING: toctree contains reference to nonexisting document 'board/ti/:doc:`../beagle/am62x_beagleplay`' [toc.not_readable]
Best regards
Heinrich
On Mon, Oct 21, 2024 at 08:15:45PM +0200, Heinrich Schuchardt wrote:
On 10/21/24 20:12, Tom Rini wrote:
On Mon, Oct 21, 2024 at 08:01:01PM +0200, Heinrich Schuchardt wrote:
Sphinx writes a warning if a page is included twice in the table of contents. Use references instead.
Signed-off-by: Heinrich Schuchardt heinrich.schuchardt@canonical.com
doc/board/ti/k3.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-)
diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst index c3513f0aee2..5d01f487622 100644 --- a/doc/board/ti/k3.rst +++ b/doc/board/ti/k3.rst @@ -32,19 +32,22 @@ K3 Based SoCs am62ax_sk am62x_sk
- ../beagle/am62x_beagleplay
- ../phytec/phycore-am62x
- ../toradex/verdin-am62 am62px_sk am64x_evm am65x_evm j7200_evm
- ../beagle/j721e_beagleboneai64 j721e_evm j721s2_evm j722s_evm j784s4_evm
+K3 SoC based boards in other sections
+* :doc:`../beagle/am62x_beagleplay` +* :doc:`../beagle/j721e_beagleboneai64` +* :doc:`../phytec/phycore-am62x` +* :doc:`../toradex/verdin-am62`
Can we just make the changes to :doc: links be inline and keep the list sorted/ordered as-is? Or does that not read well once rendered?
This is nothing Sphinx would understand:
WARNING: toctree contains reference to nonexisting document 'board/ti/:doc:`../beagle/am62x_beagleplay`' [toc.not_readable]
Hmm, maybe toctree is the wrong keyword, given where it is in the file and the rest of the contents. I think the whole list is intended as "here are all of the K3-based platforms". This however may mean that a bunch of boards then need :orphan: added as they won't strictly be in some other ToC list?
Tom Rini trini@konsulko.com schrieb am Mo., 21. Okt. 2024, 20:42:
On Mon, Oct 21, 2024 at 08:15:45PM +0200, Heinrich Schuchardt wrote:
On 10/21/24 20:12, Tom Rini wrote:
On Mon, Oct 21, 2024 at 08:01:01PM +0200, Heinrich Schuchardt wrote:
Sphinx writes a warning if a page is included twice in the table of contents. Use references instead.
Signed-off-by: Heinrich Schuchardt <
heinrich.schuchardt@canonical.com>
doc/board/ti/k3.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-)
diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst index c3513f0aee2..5d01f487622 100644 --- a/doc/board/ti/k3.rst +++ b/doc/board/ti/k3.rst @@ -32,19 +32,22 @@ K3 Based SoCs am62ax_sk am62x_sk
- ../beagle/am62x_beagleplay
- ../phytec/phycore-am62x
- ../toradex/verdin-am62 am62px_sk am64x_evm am65x_evm j7200_evm
- ../beagle/j721e_beagleboneai64 j721e_evm j721s2_evm j722s_evm j784s4_evm
+K3 SoC based boards in other sections
+* :doc:`../beagle/am62x_beagleplay` +* :doc:`../beagle/j721e_beagleboneai64` +* :doc:`../phytec/phycore-am62x` +* :doc:`../toradex/verdin-am62`
Can we just make the changes to :doc: links be inline and keep the list sorted/ordered as-is? Or does that not read well once rendered?
This is nothing Sphinx would understand:
WARNING: toctree contains reference to nonexisting document 'board/ti/:doc:`../beagle/am62x_beagleplay`' [toc.not_readable]
Hmm, maybe toctree is the wrong keyword, given where it is in the file and the rest of the contents. I think the whole list is intended as "here are all of the K3-based platforms". This however may mean that a bunch of boards then need :orphan: added as they won't strictly be in some other ToC list?
-- Tom
I would prefer not to break tree navigation. It would be best if the TI contribitors stepped in.
Best regards
Heinrich
Hi Heinrich
On 22/10/24 01:06, Heinrich Schuchardt wrote:
Tom Rini <trini@konsulko.com mailto:trini@konsulko.com> schrieb am Mo., 21. Okt. 2024, 20:42:
On Mon, Oct 21, 2024 at 08:15:45PM +0200, Heinrich Schuchardt wrote: > On 10/21/24 20:12, Tom Rini wrote: > > On Mon, Oct 21, 2024 at 08:01:01PM +0200, Heinrich Schuchardt wrote: > > > Sphinx writes a warning if a page is included twice in the table of > > > contents. Use references instead. > > > > > > Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com <mailto:heinrich.schuchardt@canonical.com>> > > > --- > > > doc/board/ti/k3.rst | 11 +++++++---- > > > 1 file changed, 7 insertions(+), 4 deletions(-) > > > > > > diff --git a/doc/board/ti/k3.rst b/doc/board/ti/k3.rst > > > index c3513f0aee2..5d01f487622 100644 > > > --- a/doc/board/ti/k3.rst > > > +++ b/doc/board/ti/k3.rst > > > @@ -32,19 +32,22 @@ K3 Based SoCs > > > am62ax_sk > > > am62x_sk > > > - ../beagle/am62x_beagleplay > > > - ../phytec/phycore-am62x > > > - ../toradex/verdin-am62 > > > am62px_sk > > > am64x_evm > > > am65x_evm > > > j7200_evm > > > - ../beagle/j721e_beagleboneai64 > > > j721e_evm > > > j721s2_evm > > > j722s_evm > > > j784s4_evm > > > +K3 SoC based boards in other sections > > > + > > > +* :doc:`../beagle/am62x_beagleplay` > > > +* :doc:`../beagle/j721e_beagleboneai64` > > > +* :doc:`../phytec/phycore-am62x` > > > +* :doc:`../toradex/verdin-am62` > > > > Can we just make the changes to :doc: links be inline and keep the list > > sorted/ordered as-is? Or does that not read well once rendered? > > > > This is nothing Sphinx would understand: > > WARNING: toctree contains reference to nonexisting document > 'board/ti/:doc:`../beagle/am62x_beagleplay`' [toc.not_readable] Hmm, maybe toctree is the wrong keyword, given where it is in the file and the rest of the contents. I think the whole list is intended as "here are all of the K3-based platforms". This however may mean that a bunch of boards then need :orphan: added as they won't strictly be in some other ToC list? -- TomI would prefer not to break tree navigation. It would be best if the TI contribitors stepped in.
I personally feel this is good enough, the toc contains the TI K3 boards present within the "K3 Generation" page while the references points to the other vendor boards.
Best regards
Heinrich
participants (3)
-
Heinrich Schuchardt -
Neha Malcom Francis -
Tom Rini