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/