Merge pull request #27 from StaticRocket/feature/no-config

Feature/no config

.github/workflows/rstcheck.yml

@@ -53,7 +53,7 @@ jobs:
           echo "$(wc -l < _new-warn.log)" > ./results/problem-count
 
           # Exit with error if there are new warnings
-          [ "$WARNING_COUNT" -gt "0" ] && exit 1
+          [ "$WARNING_COUNT" -eq "0" ]
 
       - name: Save results
         uses: actions/upload-artifact@v4

.rstcheck.cfg

@@ -3,3 +3,4 @@ ignore_directives = ifconfig
 # ignore the following languages because they require external compilers and
 # snippets in this repo depend on external code
 ignore_language = c,cpp,c++
+ignore_substitutions = __PART_FAMILY_NAME__,__PART_FAMILY_DEVICE_NAMES__,__PRODUCT_LINE_NAME__,__SDK_BUILD_MACHINE__,__SDK_FULL_NAME__,__SDK_SHORT_NAME__,__SDK_INSTALL_FILE__,__SDK_INSTALL_DIR__,__SDK_DOWNLOAD_URL__,__LINUX_UBUNTU_VERSION_LONG__,__LINUX_UBUNTU_VERSION_SHORT__,__OPTEE_PLATFORM_FLAVOR__,__RTOS_UBUNTU_VERSION_LONG__,__WINDOWS_SUPPORTED_LONG__,__FEATURINGMATRIX__,__SYSFW_CORE_NAME__,__PCIE_BASE_ADDRESS__,__PCIE_DEVICE_ID__

Makefile

@@ -20,16 +20,13 @@ export ROOTDIR = $(dir $(mkfile_path))
 $(info ROOTDIR is $(ROOTDIR))
 
 $(info DEVFAMILY is $(DEVFAMILY_UP))
-FAMILYSETUPFILE = python-scripts/family_setup.py
 
 ifeq ($(DEVFAMILY_UP), $(filter $(DEVFAMILY_UP), J721E J7200 J721S2 J784S4 AM68 AM69 J722S AM67 J742S2))
   CONFDIR = source/devices/J7_Family/${OS_LOW}
 else
   CONFDIR = source/devices/$(DEVFAMILY_UP)/${OS_LOW}
 endif
-TAGFILE = configs/$(DEVFAMILY_UP)/$(DEVFAMILY_UP)_${OS_LOW}_tags.py
 
-$(info TAGFILE is $(TAGFILE))
 $(info CONFDIR is $(CONFDIR))
 
 VERSION   = $(shell cat ${CONFDIR}/version.txt)
@@ -44,7 +41,7 @@ endif
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-CONFLOC         = -c build/
+CONFLOC         = -c $(ROOTDIR)
 VEROPTS         = -D version=${VERSION} -D release=${VERSION}
 GIT_HASH        = -D html_context.commit="$(shell git rev-parse --short HEAD)"
 ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(CONFLOC) $(VEROPTS) $(GIT_HASH)
@@ -61,10 +58,6 @@ clean:
 	rm -rf "$(BUILDDIR)"
 	rm -f source/_replacevars.rst
 
-config:
-	mkdir -pv build
-	cat python-scripts/conf.py ${TAGFILE} ${FAMILYSETUPFILE} > build/conf.py
-
 lint:
 	rstcheck -r "$(SOURCEDIR)"
 

README.md

@@ -19,72 +19,54 @@ OR you can use a docker container like the following:
 
 ### Build on Ubuntu
 
-#### Build linux documentatin
+To build the documentation a DEVFAMILY and OS must be specified as either an
+argument to `make` or set as environment variables prior to execution of `make`.
 
-    $ make clean DEVFAMILY=<FAMILY> OS=linux
-    $ make config DEVFAMILY=<FAMILY> OS=linux
-    $ make DEVFAMILY=<FAMILY> OS=linux
+DEVFAMILY represents the Device Family. Possible values correspond to the names
+of directories listed under `configs/`. For example:
 
-#### Build rtos documentation
+ * "AM335X" (representing AM335X family)
+ * "AM437X" (representing AM437X family)
+ * "AM57X" (representing AM57X family)
+ * "AM64X" (representing AM64X family)
+ * "AM62X" (representing AM62X family)
+ * "AM62AX" (representing AM62AX family)
+ * "AM62PX" (representing AM62PX family)
+ * "AM65X" (representing AM65X family)
+ * "DRA821A" (representing DRA821A)
+ * "J721E" (representing Jacinto 7 ES)
+ * "J7200" (representing Jacinto 7 VCL)
+ * "J721S2" (representing Jacinto 7 AEP)
+ * "J784S4" (representing Jacinto 7 AHP)
+ * "J722S" (representing Jacinto 7 AEN)
+ * "GEN" (representing General family not listed above)
+ * "CORESDK" (representing CORESDK)
 
-    $ make clean DEVFAMILY=<FAMILY> OS=rtos
-    $ make config DEVFAMILY=<FAMILY> OS=rtos
-    $ make DEVFAMILY=<FAMILY> OS=rtos
+OS represents the operating system. Possible values correspond to the second
+parameter of files listed under the `configs/<DEVFAMILY>/` directory. For
+example `AM57X_linux_toc.txt` means that `linux` is a valid OS value.
 
-#### Build android (available for J721E and GEN):
+Example build commands:
 
-    $ make clean DEVFAMILY=<FAMILY> OS=android
-    $ make config DEVFAMILY=<FAMILY> OS=android
-    $ make DEVFAMILY=<FAMILY> OS=android
+ - Build linux documentation for AM335X
 
-### Build am64x documentation
+    $ make DEVFAMILY=AM335X OS=linux
 
-    $ make config DEVFAMILY=AM64X
-    $ make DEVFAMILY=AM64X
+ - Build rtos documentation AM57X
 
+    $ make DEVFAMILY=AM57X OS=rtos
 
-**Note**: that DEVFAMILY represents the Device Family.
-      Possible values for <FAMILY> are
+ - Build android documentation for AM62X
 
-* "AM335X" (representing AM335X family)
-* "AM437X" (representing AM437X family)
-* "AM57X" (representing AM57X family)
-* "AM64X" (representing AM64X family)
-* "AM62X" (representing AM62X family)
-* "AM62AX" (representing AM62AX family)
-* "AM62PX" (representing AM62PX family)
-* "AM65X" (representing AM65X family)
-* "DRA821A" (representing DRA821A)
-* "J721E" (representing Jacinto 7 ES)
-* "J7200" (representing Jacinto 7 VCL)
-* "J721S2" (representing Jacinto 7 AEP)
-* "J784S4" (representing Jacinto 7 AHP)
-* "J722S" (representing Jacinto 7 AEN)
-* "GEN" (representing General family not listed above)
-* "CORESDK" (representing CORESDK)
-
-**Note**: Please use script `bin/check-warn.sh` or the `make lint` target
-          to check for new build warnings and fix them before submitting
-          pull-requests.
+    $ make DEVFAMILY=AM62X OS=android
 
 ### HTML Page Output
 
 Open the index page in a web browser
 
-**AM64X**:
-
-    ./build/processor-sdk-AM64X/esd/docs/[version]/index.html
-
-**GEN family** (TODO: to be migrated to the new structure):
-
-    linux:   ./build/processor-sdk-linux/esd/docs/[version]/index.html
-    rtos:    ./build/processor-sdk-rtos/esd/docs/[version]/index.html
-    android: ./build/processor-sdk-android/esd/docs/[version]/index.html
-
-**Others**:
-
-    linux: ./build/processor-sdk-linux-<FAMILY>/esd/docs/[version]/index.html
-    rtos:  ./build/processor-sdk-rtos-<FAMILY>/esd/docs/[version]/index.html
+    linux:   ./build/processor-sdk-linux-<FAMILY>/esd/docs/[version]/index.html
+    rtos:    ./build/processor-sdk-rtos-<FAMILY>/esd/docs/[version]/index.html
+    android: ./build/processor-sdk-android-<FAMILY>/esd/docs/[version]/index.html
 
 ## Tips and Tricks
 

python-scripts/conf.py → conf.py

@@ -11,16 +11,20 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
+# pylint: disable=C0103,W0622
+
 import sys
 import os
-import shlex
+import importlib
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #sys.path.insert(0, os.path.abspath('.'))
 rootdir = os.environ.get('ROOTDIR')
-sys.path.append(rootdir + 'python-scripts')
+sys.path.insert(0, os.path.abspath(rootdir))
+
+from scripts import interpretvalues, sectinc, replacevars
 
 # -- General configuration ------------------------------------------------
 
@@ -41,7 +45,7 @@
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['../_templates']
+templates_path = ['_templates']
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
@@ -50,8 +54,8 @@
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
-copyright = u'© Copyright 1995-2024'
-author = u'Texas Instruments Incorporated'
+copyright = '© Copyright 1995-2024'
+author = 'Texas Instruments Incorporated'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -134,7 +138,7 @@
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
-html_last_updated_fmt = u'%b %d, %Y'
+html_last_updated_fmt = '%b %d, %Y'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
@@ -239,3 +243,61 @@
 
 # Suppress warnings about excluded documents because every device gets a different toc tree
 suppress_warnings = ['toc.excluded']
+
+# -- Tag file loader ------------------------------------------------------
+
+# Defaults
+exclude_patterns = []
+
+FAMILY = os.environ.get("DEVFAMILY", "")
+OS = os.environ.get("OS", "")
+try:
+    globals().update(importlib.import_module(f"configs.{FAMILY}.{FAMILY}_{OS}_tags").__dict__)
+except ModuleNotFoundError as exc:
+    raise ModuleNotFoundError("Configuration not supported!") from exc
+
+# -- Family setup ---------------------------------------------------------
+
+# List of Inclusion TOC files to use
+family_tocfiles = [f"{FAMILY}/{FAMILY}_{OS}_toc.txt"]
+# Family Configuration file to use
+family_config_inputfile = f"{FAMILY}/{FAMILY}_{OS}_config.txt"
+
+# Hash table for Replacement Variables
+family_replacevars = {}
+# Hash table for Configuration Values
+family_configvals = {}
+
+def setup(app):
+    """
+    Sphinx application entrypoint
+    """
+
+    # Load overrides
+    app.add_css_file("css/theme_overrides.css")
+
+    # Read the replacement variables and the configuration values
+    print("Device Family Build setup started")
+    interpretvalues.read_familyvals(app, family_config_inputfile,
+                                    family_replacevars, family_configvals)
+
+    print("Build setup: Filled Replacement Variables (family_replacevars)"
+            "and Configuration Values (family_configvals) hash tables")
+    print("family_replacevars = ")
+    print(family_replacevars)
+    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(']')
+
+    # Write to the replacevars.rst.inc file for usage by Sphinx
+    replacevars.write_replacevars(app, family_replacevars)
+    print("Device Family Build setup completed")