Feature/remove toc not included warnings

.gitmodules

@@ -1,18 +1,18 @@
 [submodule "open-amp"]
 	path = open-amp
-	url = https://github.com/OpenAMP/open-amp.git
+	url = https://github.com/sipke/open-amp.git
 [submodule "hypervisorless_virtio_zcu102"]
 	path = hypervisorless_virtio_zcu102
-	url = https://github.com/danmilea/hypervisorless_virtio_zcu102.git
+	url = https://github.com/sipke/hypervisorless_virtio_zcu102.git
 [submodule "lopper"]
 	path = lopper
-	url = https://github.com/devicetree-org/lopper.git
+	url = https://github.com/sipke/lopper.git
 [submodule "openamp-system-reference"]
 	path = openamp-system-reference
-	url = https://github.com/OpenAMP/openamp-system-reference.git
+	url = https://github.com/sipke/openamp-system-reference.git
 [submodule "libmetal"]
 	path = libmetal
-	url = https://github.com/OpenAMP/libmetal.git
+	url = https://github.com/sipke/libmetal.git
 [submodule "awesome"]
 	path = _doxygen/awesome
 	url = https://github.com/jothepro/doxygen-awesome-css.git

conf.py

@@ -119,7 +119,8 @@
 html_logo  = '_static/images/openAMP_combox_dark_trim.svg'
 
 html_theme_options = {
-    'logo_only': True
+    'logo_only': True,
+    'includehidden': False
 }
 
 # below copied / hacked from Zephyr projects' zephyr/doc/conf.py

demos/echo.rst

@@ -117,3 +117,14 @@ This Echo Test Sample is demonstrated in the following reference implementations
 * :ref:`Docker Images<docker-images-label>` as demo1A
 * :ref:`AMD-Xilinx platforms<demos-AMD-work-label>`
 * :ref:`Inter Process Demos<inter-process-reference-label>`
+
+
+***************************
+Echo Test Build Information
+***************************
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+
+   ../openamp-system-reference/examples/legacy_apps/examples/echo/README

demos/hvl_virtio.rst

@@ -99,6 +99,17 @@ This Hypervisorless Virtio Samples are demonstrated in the following reference i
 For information on building and running the demonstrations for zcu102 refer to
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    ../hypervisorless_virtio_zcu102/README_demo
+   ../hypervisorless_virtio_zcu102/README
+   ../hypervisorless_virtio_zcu102/zephyr_r5/README
+   ../hypervisorless_virtio_zcu102/zephyr_r5/hello_r5/README
+
+For more information on Hypervisorless Virtio and associated OpenAMP support refer to
+
+.. toctree::
+   :maxdepth: 1
+
+   ../hypervisorless_virtio_zcu102/README_hypervisorless_virtio.md
+   ../hypervisorless_virtio_zcu102/README_openamp_virtio.md

demos/linux_rpc.rst

@@ -102,8 +102,25 @@ This Linux RPC Sample is demonstrated in the following reference implementations
 
 * :ref:`Linux Inter Process <inter-process-reference-label>`
 
+
+********************************
+Linux RPC Demo Build Information
+********************************
+
 .. toctree::
-   :maxdepth: 1
-   :caption: Demo Compile and Execution Instructions
+   :maxdepth: 2
 
    ../openamp-system-reference/examples/legacy_apps/examples/linux_rpc_demo/README
+
+
+*********************************************
+Alternate Bare Metal Remote Build Information
+*********************************************
+
+The following sections detail how to build a baremetal remote if you wish to run this example
+on a remote processor rather than secondary linux process.
+
+.. toctree::
+   :maxdepth: 2
+
+   ../openamp-system-reference/examples/legacy_apps/examples/rpc_demo/README

demos/matrix_multiply.rst

@@ -131,3 +131,14 @@ This Matrix Multiply Sample is demonstrated in the following reference implement
 * :ref:`Docker Images<docker-images-label>` as demo1B
 * :ref:`AMD-Xilinx platforms<demos-AMD-work-label>`
 * :ref:`Inter Process Demos<inter-process-reference-label>`
+
+
+*********************************
+Matrix Multiply Build Information
+*********************************
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+
+   ../openamp-system-reference/examples/legacy_apps/examples/matrix_multiply/README

demos/reference_boards.rst

@@ -19,3 +19,4 @@ number of examples. Additional supporting code is located in the
    system_reference-NXP
    system_reference-TI
    inter_process
+   ../openamp-system-reference/examples/legacy_apps/README

demos/rpmsg_multi_services.rst

@@ -216,3 +216,14 @@ This RPMsg Multi Services Sample is demonstrated in the following reference impl
 * :ref:`Texas Instruments <reference_board_TI>`
 
    * Refer to `Zephyr Build Instructions <https://github.com/OpenAMP/openamp-system-reference/tree/main/examples/zephyr/rpmsg_multi_services>`_.
+
+
+**************************************
+RPMsg Multi Services Build Information
+**************************************
+
+.. toctree::
+   :maxdepth: 2
+   :titlesonly:
+
+   ../openamp-system-reference/examples/zephyr/rpmsg_multi_services/README

demos/system_reference-AMD-Xilinx.rst

@@ -15,3 +15,10 @@ The following Reference Samples and Demos are implemented using the
    ../openamp-system-reference/examples/linux/rpmsg-echo-test/README.md
    ../openamp-system-reference/examples/linux/rpmsg-mat-mul/README.md
    ../openamp-system-reference/examples/linux/rpmsg-proxy-app/README.md
+   ../openamp-system-reference/examples/libmetal/machine/host/amd_linux_userspace/README
+   ../openamp-system-reference/examples/libmetal/machine/remote/amd_rpu/README
+   ../openamp-system-reference/examples/libmetal/machine/remote/amd_rpu/system/freertos/README
+   ../openamp-system-reference/examples/libmetal/machine/remote/amd_rpu/system/generic/README
+   ../openamp-system-reference/examples/legacy_apps/machine/xlnx/README
+   ../openamp-system-reference/examples/legacy_apps/machine/xlnx/microblaze_generic/README
+   ../openamp-system-reference/examples/linux/dts/xilinx/README

index.rst

@@ -17,3 +17,52 @@ Welcome to the OpenAMP Project Documentation
    protocol_details/index
    docs/porting_guide
    openamp/glossary
+
+
+..
+  TOC entries used to suppress warnings we accept for files not included in a table of contents.
+  WARNING: document isn't included in any toctree [toc.not_included]
+  Note that each library's (e.g. open-amp) readme file is included via the REFERENCE section links
+  in the navigation bar on the left.
+
+.. toctree::
+   :hidden:
+
+   README
+   openamp-system-reference/README
+   openamp-system-reference/LICENSE
+   open-amp/.github/actions/build_ci/README
+   open-amp/README
+   open-amp/MAINTAINERS
+   open-amp/LICENSE
+   libmetal/.github/actions/build_ci/README
+   libmetal/README
+   libmetal/MAINTAINERS
+   libmetal/LICENSE
+   lopper/LICENSE
+   lopper/specification/README
+   lopper/tests/MIGRATION_GUIDE
+   lopper/tests/README
+   lopper/README
+   lopper/README-architecture
+   lopper/specification/source/index
+   lopper/docs/amd/linux/source/index
+   lopper/docs/amd/zephyr/source/index
+   lopper/demos/openamp/README.md
+
+..
+  TOC entries for examples which do not have readthedocs descriptions so suppressing to avoid the
+  warning:
+  WARNING: document isn't included in any toctree [toc.not_included]
+  If readthedocs description is added, these should be integrated into that description.
+
+.. toctree::
+   :hidden:
+
+   openamp-system-reference/examples/legacy_apps/examples/nocopy_echo/README
+   openamp-system-reference/examples/legacy_apps/examples/rpmsg_sample_echo/README
+   openamp-system-reference/examples/libmetal/README
+   openamp-system-reference/examples/libmetal/demos/irq_shmem_demo/README
+   openamp-system-reference/examples/libmetal/demos/irq_shmem_demo/host/README
+   openamp-system-reference/examples/libmetal/demos/irq_shmem_demo/remote/README
+   openamp-system-reference/examples/zephyr/dual_qemu_ivshmem/README

openamp/overview.rst

@@ -283,17 +283,19 @@ This is achieved through the OpenAMP library which:
       (`See OpenAMP repository <https://github.com/OpenAMP>`_)
     - works on different system thanks to the `libmetal <https://github.com/libmetal>`_
       adaptation layer:
+
         - Bare Metal (No OS)
         - Multiple RTOS's, including `FreeRTOS <https://freertos.org/>`_,
           `NuttX <https://nuttx.apache.org/>`_, `Zephyr <https://www.zephyrproject.org/>`_,
           `VxWorks <https://www.windriver.com/products/vxworks>`_, and more
+
         - OS's on top of hypervisors
         - Within hypervisors
     - is compatible with different compilers such as gcc, clang, armcc and more
     - maintains compatibility with the Linux kernel by leveraging the following frameworks:
       `remoteproc <https://www.kernel.org/doc/html/latest/staging/remoteproc.html>`_,
       `RPMsg <https://www.kernel.org/doc/html/latest/staging/rpmsg.html>`_ and
-      `Virtio <https://docs.kernel.org/driver-api/virtio/virtio.html>`_ frameworks.
+      `Virtio Driver <https://docs.kernel.org/driver-api/virtio/virtio.html>`_ frameworks.
 
 
 .. _governance-work-label:

tools/index.rst

@@ -4,11 +4,10 @@
 OpenAMP Supporting Tools
 =========================
 
+Lopper
+------
+
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
 
    lopper
-   ../lopper/demos/openamp/README.md
-
-* Run the Lopper Demonstration as demo5 in :ref:`Docker Images<docker-images-label>`.

tools/lopper.rst

@@ -1,44 +1,6 @@
-===================
-OpenAMP Lopper Tool
-===================
 
-.. _lopper-tool-intro:
 
-***************
-Lopper Intro
-***************
+.. toctree::
+   :maxdepth: 1
 
-System Device Trees (S-DT) are used to describe resources of `heterogeneous <https://en.wikipedia.org/wiki/Heterogeneous_computing>`_ embedded environments.
-
-Their intent is to be the industry standard method for defining how computing resources are divided into independent :ref:`runtime domains<resource-assignment-work-label>`.
-
-Examples of domains are
-
-* a computing unit, e.g. RTOS on R5s
-* an operating environment at a specific execution level (e.g. `OPTEE <https://optee.readthedocs.io/en/latest/general/about.html>`_)
-* a virtual machine (e.g. `Xen <https://xenproject.org/>`_)
-
-For those familiar with `Device Trees (DTS) <https://www.kernel.org/doc/html/latest/devicetree/usage-model.html>`_ think of the S-DT as a combination of multiple device trees to define sub-systems. DTS' define resources seen from one address space, whereas S-DT's define the topology of the full system.
-
-The `Lopper Tool <https://github.com/devicetree-org/lopper>`_ provides a way to generate sub-system DTS' from S-DT's and manipulate, inspect or verify the S-DT for correctness.
-
-..  image::  ../images/tools/lopper-intro.svg
-
-
-The `Lopper Tool <https://github.com/devicetree-org/lopper>`_ is a data driven tool written in Python, and supports inputs in dts, dtb and yaml format. Actions, which are used to manipulate the input data, are provided as unit operations (lops) as DTS formatted files. These are small transformation commands, inline Python source or for more complex scenarios `lopper assists <https://github.com/devicetree-org/lopper/tree/master/lopper/assists>`_ Python modules.
-
-The diagram below shows an example of three transformations performed by lopper through three independent DTS files which define the actions to perform.
-
-..  image::  ../images/tools/lopper-actions.svg
-
-Lopper is built on top of device tree tools, `Device Tree Compiler (DTC) <https://github.com/torvalds/linux/tree/master/scripts/dtc>`_ and `libfdt <https://github.com/torvalds/linux/tree/master/scripts/dtc/libfdt>`_.
-
-
-References
-^^^^^^^^^^
-
-:ref:`Lopper Architecture Readme<lopper/README-architecture:lopper processing flow:>`
-
-`Linaro Connect 2020 - System Device Tree & Lopper Slide Set <https://static.linaro.org/connect/lvc20/presentations/LVC20-314-0.pdf>`_
-
-`Open Source Summit 2022 Slide Set <https://static.sched.com/hosted_files/ossna2022/d9/Lopper%20ELCNA%202022.pdf>`_
+   lopper_intro

tools/lopper_intro.rst

@@ -0,0 +1,43 @@
+
+.. _lopper-tool-intro:
+
+====================
+OpenAMP Lopper Intro
+====================
+
+System Device Trees (S-DT) are used to describe resources of `heterogeneous <https://en.wikipedia.org/wiki/Heterogeneous_computing>`_ embedded environments.
+
+Their intent is to be the industry standard method for defining how computing resources are divided into independent :ref:`runtime domains<resource-assignment-work-label>`.
+
+Examples of domains are
+
+* a computing unit, e.g. RTOS on R5s
+* an operating environment at a specific execution level (e.g. `OPTEE <https://optee.readthedocs.io/en/latest/general/about.html>`_)
+* a virtual machine (e.g. `Xen <https://xenproject.org/>`_)
+
+For those familiar with `Device Trees (DTS) <https://www.kernel.org/doc/html/latest/devicetree/usage-model.html>`_ think of the S-DT as a combination of multiple device trees to define sub-systems. DTS' define resources seen from one address space, whereas S-DT's define the topology of the full system.
+
+The `Lopper Tool <https://github.com/devicetree-org/lopper>`_ provides a way to generate sub-system DTS' from S-DT's and manipulate, inspect or verify the S-DT for correctness.
+
+..  image::  ../images/tools/lopper-intro.svg
+
+
+The `Lopper Tool <https://github.com/devicetree-org/lopper>`_ is a data driven tool written in Python, and supports inputs in dts, dtb and yaml format. Actions, which are used to manipulate the input data, are provided as unit operations (lops) as DTS formatted files. These are small transformation commands, inline Python source or for more complex scenarios `lopper assists <https://github.com/devicetree-org/lopper/tree/master/lopper/assists>`_ Python modules.
+
+The diagram below shows an example of three transformations performed by lopper through three independent DTS files which define the actions to perform.
+
+..  image::  ../images/tools/lopper-actions.svg
+
+Lopper is built on top of device tree tools, `Device Tree Compiler (DTC) <https://github.com/torvalds/linux/tree/master/scripts/dtc>`_ and `libfdt <https://github.com/torvalds/linux/tree/master/scripts/dtc/libfdt>`_.
+
+Run the Lopper Demonstration as demo5 in :ref:`Docker Images<docker-images-label>`.
+
+
+References
+^^^^^^^^^^
+
+`Linaro Connect 2020 - System Device Tree & Lopper Slide Set <https://static.linaro.org/connect/lvc20/presentations/LVC20-314-0.pdf>`_
+
+`Open Source Summit 2022 Slide Set <https://static.sched.com/hosted_files/ossna2022/d9/Lopper%20ELCNA%202022.pdf>`_
+
+`Lopper Repository <https://github.com/devicetree-org/lopper>`_