Merge pull request #1 from StaticRocket/test

Docker: Add docker container under subdir with required packages

.github/workflows/docker.yml

@@ -0,0 +1,58 @@
+---
+name: Docker Workflow
+on:
+  push:
+    branches: [master]
+    paths:
+      - docker
+      - requirements.txt
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log into registry ${{ env.REGISTRY }}
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          flavor: latest=true
+          tags: |
+            type=ref,event=branch
+            type=sha
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+
+      - name: Setup context
+        run: make -C docker setup
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          platforms: linux/amd64
+          context: docker
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

README.md

@@ -5,15 +5,13 @@ Processor SDK Documentation in Sphinx
 
 ### Install tools on Ubuntu
 
-    $ sudo apt-get install python-sphinx
-
-OR use the following command in a python virtual environment for a known working
-config as of 2023/09/05:
+Use the following command in a python virtual environment for a known working
+config:
 
     # python3 -m pip install -r requirements.txt
 
 OR you can use a docker container like the following:
-    - [psdk-doc-docker](https://github.com/StaticRocket/psdk-doc-docker/pkgs/container/psdk-doc-docker)
+    - [psdk-doc-docker](https://github.com/TexasInstruments/processor-sdk-doc/pkgs/container/processor-sdk-doc)
 
 ### Clone the Git Repo
 

docker/.gitignore

@@ -0,0 +1 @@
+requirements.txt

docker/Dockerfile

@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: MIT
+# Copyright (C) 2024 Texas Instruments Incorporated - https://www.ti.com
+
+FROM debian:stable-slim
+
+RUN apt-get update \
+	&& DEBIAN_FRONTEND=noninteractive apt-get install -y \
+		--no-install-recommends \
+		dumb-init \
+		git \
+		gosu \
+		make \
+		python3-pip \
+		ripgrep \
+		zip \
+	&& echo "**** create abc user and make our folders ****" \
+	&& useradd -u 1000 -U -d /config -s /bin/false abc \
+	&& usermod -G users abc \
+	&& mkdir /build && chown abc:abc /build \
+	&& mkdir /config && chown abc:abc /config \
+	&& echo "**** cleanup ****" \
+	&& apt-get autoremove \
+	&& apt-get clean \
+	&& rm -rf \
+		/tmp/* \
+		/var/cache/debconf/*-old \
+		/var/lib/apt/lists/* \
+		/var/lib/dpkg/status-old \
+		/var/lib/sgml-base/supercatalog.old \
+		/var/log/apt/term.log \
+		/var/tmp/*
+
+RUN --mount=type=bind,source=requirements.txt,target=/tmp/requirements.txt \
+	python3 -m pip install -r /tmp/requirements.txt --no-cache-dir \
+		--break-system-packages
+
+COPY root/ /
+
+WORKDIR /build
+VOLUME /build
+
+ENTRYPOINT ["/init"]
+CMD ["/bin/bash"]

docker/Makefile

@@ -0,0 +1,23 @@
+# SPDX-License-Identifier: MIT
+# Copyright (C) 2024 Texas Instruments Incorporated - https://www.ti.com
+
+ifeq ($(CONTAINER_TOOL),)
+  $(info CONTAINER_TOOL unset, checking if docker is present...)
+  ifneq ($(shell which docker 2> /dev/null),)
+    $(info Using docker for build...)
+    CONTAINER_TOOL := docker
+  else ifneq ($(shell which podman 2> /dev/null),)
+    $(info Using podman for build...)
+    CONTAINER_TOOL := podman
+  endif
+endif
+
+.PHONY: all setup
+all: Dockerfile setup
+	$(CONTAINER_TOOL) build . -t texasinstruments/processor-sdk-doc \
+		$(BUILD_ARGS)
+
+setup: requirements.txt
+
+requirements.txt:
+	cp -ar ../requirements.txt .

docker/README.md

@@ -0,0 +1,33 @@
+# psdk-doc-docker
+
+A simple docker container to build
+[processor-sdk-doc](https://github.com/TexasInstruments/processor-sdk-doc).
+
+
+## Why
+
+Preempting incompatibility as that repos is still using some deprecated sphinx
+calls. Sphinx has some dependency resolution issues when mixing system and local
+python library installations that causes unusual artifacts. This guarantees a
+reproducible build output.
+
+
+## Building
+
+You need podman or docker for building. If either one of those is already
+installed then just run `make`.
+
+
+## Usage
+
+New tooling has unified the invocation of Podman and Docker by fetching the
+owner of the build directory and remapping an internal user to satisfy build
+requirements. It will fail if the directory owner is in a reserved uid/gid
+region.
+
+After starting the container with your preferred container tool, follow the
+instructions for building the documentation as usual.
+
+```bash
+docker run -it --rm -v "$PWD":/build ghcr.io/texasinstruments/processor-sdk-doc
+```

docker/root/init

@@ -0,0 +1,46 @@
+#!/bin/bash
+
+# SPDX-License-Identifier: MIT
+# Copyright (C) 2024 Texas Instruments Incorporated - https://www.ti.com
+
+get_attribs() {
+	local file_stats file_to_test useful_attribs
+	if file_to_test=$(realpath "$1") && [[ $2 =~ ^[0-9]+$ ]] ; then
+		useful_attribs=$(stat "$file_to_test" -t)
+		read -r -a file_stats <<< "${useful_attribs#"$file_to_test"}"
+		echo "${file_stats["$2"]}"
+	else
+		return 1
+	fi
+}
+
+get_build_uid() {
+	get_attribs /build 3
+}
+
+get_build_gid() {
+	get_attribs /build 4
+}
+
+if NEW_GID=$(get_build_gid) && NEW_UID=$(get_build_uid); then
+	# bypass everything if podman is remapping the id to root
+	if [ "${NEW_UID}" == "0" ]; then
+		if [ "$(id -u)" == "0" ]; then
+			exec dumb-init -- "$@"
+		else
+			echo "Unable to resolve ns mapping!"
+		fi
+	fi
+
+	# change the uid and gid of abc otherwise
+	[ "$NEW_GID" != "$(id -g abc)" ] && groupmod -g "${NEW_GID}" abc
+	[ "$NEW_UID" != "$(id -u abc)" ] && usermod -u "${NEW_UID}" abc
+else
+	echo "Not able to detect UID/GID for remapping!"
+fi
+
+if [ "$(id -u)" == "$(id -u abc)" ]; then
+	exec dumb-init -- "$@"
+else
+	exec dumb-init -- gosu abc "$@"
+fi

requirements.txt

@@ -21,3 +21,4 @@ sphinxcontrib-jsmath==1.0.1
 sphinxcontrib-qthelp==1.0.3
 sphinxcontrib-serializinghtml==1.1.5
 urllib3==2.2.1
+rstcheck==3.3.1