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 <rs@ti.com>

Author: StaticRocket

README.md

@@ -1,95 +1,110 @@
-Processor SDK Documentation in Sphinx
-=====================================
+# Processor software development kit documentation
 
-## Instructions to build the project on Ubuntu
+This repository holds the documentation for the Texas Instruments Processor
+Software Development Kit (PSDK). It currently uses Sphinx and reStructuredText.
+There are some light plugins and a custom configuration tool to handle platform
+specific values.
 
-### Clone the Git Repo
+## Build guide
 
-    $ git clone https://github.com/TexasInstruments/processor-sdk-doc.git
+If you know what you are doing and just need a 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:
+If you have any questions about the preceding command, see the following
+sections.
 
-    $ cd processor-sdk-doc
-    $ python3 -m pip install -r requirements.txt
+### Clone the repository
 
-> [!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.
+```
+git clone https://github.com/TexasInstruments/processor-sdk-doc.git
+```
 
-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)
+### Start the container
 
-### Build on Ubuntu
+A lightweight container with all required dependencies is available on the
+GitHub container registry. The source code to build this container is available
+under the [`docker/`](docker/) subdirectory.
 
-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`.
+To start the container, issue the following at the root of the project.
 
-DEVFAMILY represents the Device Family. Possible values correspond to the names
-of directories listed under `configs/`. For example:
+```
+docker run -it --rm -v "$PWD":/build ghcr.io/texasinstruments/processor-sdk-doc:latest
+```
 
- * "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)
+### Issue make
 
-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.
-
-Example build commands:
-
- - Build linux documentation for AM335X
-
-       $ make DEVFAMILY=AM335X OS=linux
-
- - Build android documentation for AM62X
+GNU Make handles some initial configuration. Specify the `DEVFAMILY` and `OS`
+values as either arguments to `make` or as environment variables before
+execution of `make`.
 
-       $ make DEVFAMILY=AM62X OS=android
+`DEVFAMILY` represents the Device Family. Possible values correspond to the
+names of directories listed under [`configs/`](configs/). For example:
 
- - Build debian documentation for AM62PX
+   - "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)
 
-       $ make DEVFAMILY=AM62PX OS=debian
-
- - Build EdgeAI documentation for AM62AX
-
-       $ make DEVFAMILY=AM62AX OS=edgeai
-
-### HTML Page Output
+`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.
 
-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 possible. The output is available in directories
+matching the following structure 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
+## Development previews through GitHub Pages
 
-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.
+GitHub Pages are now live for all `DEVFAMILY` and `OS` supported by this
+repository. This means that the current `master` branch build is available on
+GitHub Pages.
 
 You can access the latest bleeding-edge documentation at the following link:
-    - [Processor SDK Documentation](https://texasinstruments.github.io/processor-sdk-doc/)
+https://texasinstruments.github.io/processor-sdk-doc/
 
-Please treat GitHub Pages as the most up-to-date source of documentation.
+Please treat the GitHub Pages deployment as the most up-to-date source of
+documentation.