From 13bd6949e98060199bc6b4d3372ecd91899f95e1 Mon Sep 17 00:00:00 2001 From: Randolph Sapp Date: Thu, 11 Dec 2025 17:03:47 -0600 Subject: [PATCH] docs(readme): simplify the readme and example make At this point we should drive users to the container properly. That gives them access to almost all of the CI tools and ensures the output they generate will match what we expect. Advanced users can still parse the requirements.txt if they want. Also, add an example make command using the container to the top of the build guide since that is one of the more popular things I need to remind people about. Signed-off-by: Randolph Sapp --- README.md | 134 +++++++++++++++++++++++++----------------------------- 1 file changed, 61 insertions(+), 73 deletions(-) diff --git a/README.md b/README.md index 21a3b7375..75257f5aa 100644 --- a/README.md +++ b/README.md @@ -1,95 +1,83 @@ -Processor SDK Documentation in Sphinx -===================================== +# Processor SDK documentation -## Instructions to build the project on Ubuntu +This is the documentation for the Texas Instruments Processor Software +Development Kit (PSDK). It uses Sphinx and reStructuredText. There are some +light plugins and a custom configuration tool to handle device specific values. -### Clone the Git Repo +## Build guide - $ git clone https://github.com/TexasInstruments/processor-sdk-doc.git +Continue reading if you have any questions about the following command. -### Install tools on Ubuntu +``` +docker run -it --rm -v "$PWD":/build ghcr.io/texasinstruments/processor-sdk-doc:latest make DEVFAMILY=AM62X OS=linux +``` -Use the following command in a python virtual environment for a known working -config: +### Clone the repository - $ cd processor-sdk-doc - $ python3 -m pip install -r requirements.txt +``` +git clone https://github.com/TexasInstruments/processor-sdk-doc.git +``` -> [!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. +### Start the container -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) +A small container with all required tools is available on the GitHub. The source +is in the [`docker/`](docker/) subdirectory. -### Build on Ubuntu +To start the container, issue the following at the root of the project. -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`. +``` +docker run -it --rm -v "$PWD":/build ghcr.io/texasinstruments/processor-sdk-doc:latest +``` -DEVFAMILY represents the Device Family. Possible values correspond to the names -of directories listed under `configs/`. For example: +### Issue make - * "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) - * "AM62LX" (representing AM62L family) - * "AM62DX" (representing AM62D 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) +GNU Make handles some initial setup. Specify the `DEVFAMILY` and `OS` values as +either arguments to `make` or as environment variables. -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. +`DEVFAMILY` stands for the Device Family. Possible values correspond to the +names of directories listed under [`configs/`](configs/). -Example build commands: - - - Build linux documentation for AM335X - - $ make DEVFAMILY=AM335X OS=linux - - - Build android documentation for AM62X - - $ make DEVFAMILY=AM62X OS=android - - - Build debian documentation for AM62PX +`OS` stands for the operating system. Possible values correspond to the second +part of files listed under the `configs//` directory. For example +`AM57X_linux_toc.txt` means that `linux` is a valid `OS` value. - $ make DEVFAMILY=AM62PX OS=debian - - - Build EdgeAI documentation for AM62AX - - $ make DEVFAMILY=AM62AX OS=edgeai - -### HTML Page Output - -Open the index page in a web browser +Example build commands: - linux: ./build/processor-sdk-linux-/esd/docs/[version]/index.html - android: ./build/processor-sdk-android-/esd/docs/[version]/index.html - debian: ./build/processor-sdk-debian-/esd/docs/[version]/index.html - edgeai: ./build/processor-sdk-edgeai-/esd/docs/[version]/index.html + - Build Linux documentation for AM335X + ``` + make DEVFAMILY=AM335X OS=linux + ``` + - Build Android documentation for AM62X + ``` + make DEVFAMILY=AM62X OS=android + ``` + - Build Debian documentation for AM62PX + ``` + make DEVFAMILY=AM62PX OS=debian + ``` + - Build EdgeAI documentation for AM62AX + ``` + make DEVFAMILY=AM62AX OS=edgeai + ``` + +### Document output + +Currently only HTML output is supported. The output is available in directories +matching the following template on a successful build: + +``` +./build/processor-sdk--/esd/docs//index.html +``` ## Contributing -See the [contribution guidelines](CONTRIBUTING.md) for information about -formatting guidelines, workflows, and common issues. - -## Live Preview on GitHub Pages +See [CONTRIBUTING.md](CONTRIBUTING.md) for information about formatting, +workflows, and common issues. -GitHub Pages are now live for all `DEVFAMILY` and `OS` supported by this repository. -This means that for every pull request merged into the master branch, an equivalent -preview will be available on GitHub Pages immediately. +## Development previews through GitHub Pages -You can access the latest bleeding-edge documentation at the following link: - - [Processor SDK Documentation](https://texasinstruments.github.io/processor-sdk-doc/) +GitHub Pages are now live for all `DEVFAMILY` and `OS` supported by this +project. This means that the current `master` build is on GitHub +Pages at the following link. -Please treat GitHub Pages as the most up-to-date source of documentation. +https://texasinstruments.github.io/processor-sdk-doc/