Merge branch 'TexasInstruments:master' into master

Author: h-nagalla

.github/workflows/deploy.yml

@@ -38,7 +38,7 @@ jobs:
           EOF
 
           for path in build/*/; do
-            root_index=$(find "$path" -name index.html | sort -u | tail -1)
+            root_index=$(find "$path" -name index.html -print -quit)
             if [ -n "$root_index" ]; then
               text=$(basename "$path")
               relative_path=$(realpath "$root_index" --relative-to=build)

README.md

@@ -3,20 +3,25 @@ Processor SDK Documentation in Sphinx
 
 ## Instructions to build the project on Ubuntu
 
+### Clone the Git Repo
+
+    $ git clone https://github.com/TexasInstruments/processor-sdk-doc.git
+
 ### Install tools on Ubuntu
 
 Use the following command in a python virtual environment for a known working
 config:
 
-    # python3 -m pip install -r requirements.txt
+    $ cd processor-sdk-doc
+    $ python3 -m pip install -r requirements.txt
+
+> [!WARNING]
+> This is supported using Python v3.12+. If using an older Python version, some package versions in `requirements.txt` may not be compatible, possibly due to an older
+> bundled `pip` version.
 
 OR you can use a docker container like the following:
     - [psdk-doc-docker](https://github.com/TexasInstruments/processor-sdk-doc/pkgs/container/processor-sdk-doc)
 
-### Clone the Git Repo
-
-    $ git clone https://github.com/TexasInstruments/processor-sdk-doc.git
-
 ### Build on Ubuntu
 
 To build the documentation a DEVFAMILY and OS must be specified as either an
@@ -51,23 +56,23 @@ Example build commands:
 
  - Build linux documentation for AM335X
 
-    $ make DEVFAMILY=AM335X OS=linux
+       $ make DEVFAMILY=AM335X OS=linux
 
  - Build android documentation for AM62X
 
-    $ make DEVFAMILY=AM62X OS=android
+       $ make DEVFAMILY=AM62X OS=android
 
  - Build debian documentation for AM62PX
 
-    $ make DEVFAMILY=AM62PX OS=debian
+       $ make DEVFAMILY=AM62PX OS=debian
 
 ### HTML Page Output
 
 Open the index page in a web browser
 
     linux:   ./build/processor-sdk-linux-<FAMILY>/esd/docs/[version]/index.html
     android: ./build/processor-sdk-android-<FAMILY>/esd/docs/[version]/index.html
-    debian: ./build/processor-sdk-debian-<FAMILY>/esd/docs/[version]/index.html
+    debian:  ./build/processor-sdk-debian-<FAMILY>/esd/docs/[version]/index.html
 
 ## Live Preview on GitHub Pages
 

bin/rename.py

@@ -162,7 +162,7 @@ def update_directives(**kwargs):
         """Replace old include and image/figure statements"""
         ref_destination = (
             ' '
-            + destination.relative_to(kwargs["file"], walk_up=True).as_posix()
+            + destination.relative_to(kwargs["file"].parent, walk_up=True).as_posix()
             + "\n"
         )
 
@@ -182,7 +182,7 @@ def update_inlines(**kwargs):
         ref_destination = (
             "`"
             + destination.with_suffix("")
-            .relative_to(kwargs["file"], walk_up=True)
+            .relative_to(kwargs["file"].parent, walk_up=True)
             .as_posix()
             + "`"
         )

conf.py

@@ -260,9 +260,6 @@
 
 # -- Tag file loader ------------------------------------------------------
 
-# Defaults
-exclude_patterns = []
-
 FAMILY = os.environ.get("DEVFAMILY", "")
 OS = os.environ.get("OS", "")
 try:
@@ -277,6 +274,9 @@
 # Family Configuration file to use
 family_config_inputfile = f"{FAMILY}/{FAMILY}_{OS}_config.txt"
 
+# Set document exclusion list from the tocfiles
+exclude_patterns = sectinc.generate_exclude_patterns(family_tocfiles)
+
 # Hash table for Replacement Variables and Config Values
 family_replacevars, family_configvals = interpretvalues.read_familyvals(family_config_inputfile)
 
@@ -299,16 +299,6 @@ def setup(app):
     print("family_configvals = ")
     print(family_configvals)
 
-    # Determine which sections need to be excluded
-    sectinc.find_all_rst_files(app, exclude_patterns)
-    sectinc.fill_docs_to_keep(app, family_tocfiles, 0)
-    sectinc.set_excluded_docs(app, exclude_patterns)
-    print(FAMILY + " exclude_patterns is:")
-    print('[')
-    for elem in exclude_patterns:
-        print(elem)
-    print(']')
-
     # Load family config values into application context
     for key, value in family_configvals.items():
         app.add_config_value(key, value, 'env')

configs/AM335X/AM335X_linux_tags.py

@@ -9,9 +9,5 @@
 # The master toctree document.
 master_doc = 'devices/AM335X/linux/index'
 
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-exclude_patterns = ['rtos', 'android', 'linux/index.rst', 'devices/AM335X/rtos', 'devices/AM437X', 'devices/AM64X', 'devices/AM65X', 'devices/J7_Family', 'devices/DRA821A', 'devices/AM62X', 'devices/AM62AX', 'devices/AM62PX', 'devices/AM62LX']
-
 # OS for the build. Sphinx uses source/{sdk_os} when looking for doc inputs
 sdk_os = 'linux'

configs/AM335X/AM335X_linux_toc.txt

@@ -36,7 +36,6 @@ linux/Foundational_Components/U-Boot/UG-UART
 linux/Foundational_Components/U-Boot/UG-UFS
 linux/Foundational_Components/U-Boot/UG-DDR3
 linux/Foundational_Components/U-Boot/Applications
-linux/Foundational_Components/U-Boot/Apps-SPL-Debug
 linux/Foundational_Components/U-Boot/Apps-SPL-Debug-OpenOCD
 linux/Foundational_Components/U-Boot/Apps-Load-in-CCS
 linux/Foundational_Components/U-Boot/Apps-Splash-Screen
@@ -96,7 +95,7 @@ linux/Foundational_Components/Machine_Learning/tidl
 linux/Foundational_Components/Machine_Learning/tflite
 linux/Foundational_Components/Machine_Learning/tvm
 
-linux/Foundational_Components_Graphics
+linux/Foundational_Components/Graphics/index
 linux/Foundational_Components/Graphics/Common/Display
 linux/Foundational_Components/Graphics/Common/GTK+_Graphics_Framework
 linux/Foundational_Components/Graphics/Common/OpenGL_ES

configs/AM437X/AM437X_linux_tags.py

@@ -9,9 +9,5 @@
 # The master toctree document.
 master_doc = 'devices/AM437X/linux/index'
 
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-exclude_patterns = ['rtos', 'android', 'linux/index.rst', 'devices/AM437X/rtos', 'devices/AM335X', 'devices/AM64X', 'devices/AM65X', 'devices/J7_Family', 'devices/DRA821A', 'devices/AM62X', 'devices/AM62AX', 'devices/AM62PX', 'devices/AM62LX']
-
 # OS for the build. Sphinx uses source/{sdk_os} when looking for doc inputs
 sdk_os = 'linux'

configs/AM437X/AM437X_linux_toc.txt

@@ -37,7 +37,6 @@ linux/Foundational_Components/U-Boot/UG-UART
 linux/Foundational_Components/U-Boot/UG-UFS
 linux/Foundational_Components/U-Boot/UG-DDR3
 linux/Foundational_Components/U-Boot/Applications
-linux/Foundational_Components/U-Boot/Apps-SPL-Debug
 linux/Foundational_Components/U-Boot/Apps-SPL-Debug-OpenOCD
 linux/Foundational_Components/U-Boot/Apps-Load-in-CCS
 linux/Foundational_Components/U-Boot/Apps-TroubleShooting
@@ -97,7 +96,7 @@ linux/Foundational_Components/Machine_Learning/tidl
 linux/Foundational_Components/Machine_Learning/tflite
 linux/Foundational_Components/Machine_Learning/tvm
 
-linux/Foundational_Components_Graphics
+linux/Foundational_Components/Graphics/index
 linux/Foundational_Components/Graphics/Common/Display
 linux/Foundational_Components/Graphics/Common/GTK+_Graphics_Framework
 linux/Foundational_Components/Graphics/Common/OpenGL_ES

configs/AM57X/AM57X_linux_tags.py

@@ -9,9 +9,5 @@
 # The master toctree document.
 master_doc = 'devices/AM57X/linux/index'
 
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-exclude_patterns = ['rtos', 'android', 'linux/index.rst', 'devices/AM57X/rtos', 'devices/AM335X', 'devices/AM437X', 'devices/AM64X', 'devices/AM65X', 'devices/J7_Family', 'devices/DRA821A', 'devices/AM62X', 'devices/AM62AX', 'devices/AM62PX', 'devices/AM62LX']
-
 # OS for the build. Sphinx uses source/{sdk_os} when looking for doc inputs
 sdk_os = 'linux'

configs/AM57X/AM57X_linux_toc.txt

@@ -37,7 +37,7 @@ linux/Foundational_Components/U-Boot/UG-SATA
 linux/Foundational_Components/U-Boot/UG-DDR3
 linux/Foundational_Components/U-Boot/UG-RemoteProc
 linux/Foundational_Components/U-Boot/Applications
-linux/Foundational_Components/U-Boot/Apps-SPL-Debug
+linux/Foundational_Components/U-Boot/Apps-SPL-Debug-OpenOCD
 linux/Foundational_Components/U-Boot/Apps-Load-in-CCS
 linux/Foundational_Components/U-Boot/Apps-TroubleShooting
 linux/Foundational_Components_Boot_Monitor
@@ -98,7 +98,7 @@ linux/Foundational_Components_CMEM
 linux/Foundational_Components_OPTEE
 linux/Foundational_Components_ATF
 
-linux/Foundational_Components_Graphics
+linux/Foundational_Components/Graphics/index
 linux/Foundational_Components/Graphics/Common/Display
 linux/Foundational_Components/Graphics/Common/GTK+_Graphics_Framework
 linux/Foundational_Components/Graphics/Common/OpenGL_ES