docs(readme): simplify the readme and example make

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/<DEVFAMILY>/` 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/<DEVFAMILY>/` 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-<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
-    edgeai:  ./build/processor-sdk-edgeai-<FAMILY>/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-<OS>-<DEVFAMILY>/esd/docs/<VERSION>/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/