diff --git a/.github/workflows/rstcheck.yml b/.github/workflows/rstcheck.yml index f21938278..a827aa351 100644 --- a/.github/workflows/rstcheck.yml +++ b/.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 diff --git a/.rstcheck.cfg b/.rstcheck.cfg index 6723d451b..835c41fc7 100644 --- a/.rstcheck.cfg +++ b/.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__ diff --git a/Makefile b/Makefile index 089f0ab41..a44f80c7c 100644 --- a/Makefile +++ b/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)" diff --git a/README.md b/README.md index 4fc14d053..1cec4af3d 100644 --- a/README.md +++ b/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= OS=linux - $ make config DEVFAMILY= OS=linux - $ make DEVFAMILY= 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= OS=rtos - $ make config DEVFAMILY= OS=rtos - $ make DEVFAMILY= OS=rtos +OS represents the operating system. Possible values correspond to the second +parameter of files listed under the `configs//` 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= OS=android - $ make config DEVFAMILY= OS=android - $ make DEVFAMILY= 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 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-/esd/docs/[version]/index.html - rtos: ./build/processor-sdk-rtos-/esd/docs/[version]/index.html + 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 ## Tips and Tricks diff --git a/python-scripts/conf.py b/conf.py similarity index 77% rename from python-scripts/conf.py rename to conf.py index d98ef63f9..846721229 100644 --- a/python-scripts/conf.py +++ b/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") diff --git a/python-scripts/family_setup.py b/python-scripts/family_setup.py deleted file mode 100644 index 787fa93a5..000000000 --- a/python-scripts/family_setup.py +++ /dev/null @@ -1,80 +0,0 @@ -############################################# -# Sphinx build setup -############################################# - -# Set 'project' = General information about the Sphinx project -# Set 'html_title' = The name for this set of Sphinx documents. -# If None, it defaults to " v documentation". - -# todo: the defines below will be moved to configs//dev__tags.py -# with the new structure. Remove this section as well as "sdk_product" in *tags.py -# after the new structure is used for all the device families -if sdk_os == 'linux': - if sdk_product == 'general': - project = u'Processor SDK Linux' - html_title = 'Processor SDK Linux Documentation' - if sdk_product == 'automotive': - project = u'Processor SDK Linux Automotive' - html_title = 'Processor SDK Linux Automotive Documentation' -if sdk_os == 'rtos': - if sdk_product == 'general': - project = u'Processor SDK RTOS' - html_title = 'Processor SDK RTOS Documentation' - if sdk_product == 'automotive': - project = u'Processor SDK RTOS Automotive' - html_title = 'Processor SDK RTOS Automotive Documentation' -if sdk_os == 'android': - if sdk_product == 'general': - project = u'Processor SDK Android' - html_title = 'Processor SDK Android Documentation' - if sdk_product == 'automotive': - project = u'Processor SDK Android Automotive' - html_title = 'Processor SDK Android Automotive Documentation' - -############################################# -# Device family build setup -############################################# -import pprint -import replacevars -import sectinc -import interpretvalues - -# List of Inclusion TOC files to use -family_tocfiles = [fam_name + '/' + fam_name + '_' + sdk_os + '_toc.txt'] -# Family Configuration file to use -family_config_inputfile = fam_name + '/' + fam_name + '_' + sdk_os + '_config.txt' - -# Hash table for Replacement Variables -family_replacevars = {} -# Hash table for Configuration Values -family_configvals = {} - -# Setup Function does the following: -# 1. Reads all the replacement variables and configuration values in __config.txt -# 2. Traverses toctree files to create master list of all possible included .rst files -# 3. Create exclusion list based on the files included in the defined family_tocfiles -# 4. Update exclude_patterns so that these files are excluded from the build -# 5. Write to the Linux folder's replacevars.rst.inc for all the substitution variables - -def setup(app): - 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 = ") - pprint.pprint(family_replacevars) - print("family_configvals = ") - pprint.pprint(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(fam_name + " 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") diff --git a/python-scripts/interpretvalues.py b/scripts/interpretvalues.py similarity index 100% rename from python-scripts/interpretvalues.py rename to scripts/interpretvalues.py diff --git a/python-scripts/replacevars.py b/scripts/replacevars.py similarity index 100% rename from python-scripts/replacevars.py rename to scripts/replacevars.py diff --git a/python-scripts/sectinc.py b/scripts/sectinc.py similarity index 100% rename from python-scripts/sectinc.py rename to scripts/sectinc.py