From 25ff9c7129d42f577216af37a640aa5e1f0da651 Mon Sep 17 00:00:00 2001 From: Jacob Coffee Date: Fri, 2 Aug 2024 11:16:14 -0500 Subject: [PATCH 1/3] feat(docs): add autobuild and serving for docs --- Makefile | 16 ++++++++++++++++ docs/requirements.txt | 1 + 2 files changed, 17 insertions(+) create mode 100644 Makefile diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..41273fe5 --- /dev/null +++ b/Makefile @@ -0,0 +1,16 @@ +PIP_COMMAND := $(shell command -v uv >/dev/null 2>&1 && echo "uv pip" || echo "pip") +ENV_PREFIX = .venv/bin/ + +docs-install: ## Install docs dependencies + @echo "=> Installing documentation dependencies" + @$(PIP_COMMAND) install -r docs/requirements.txt + @echo "=> Installed documentation dependencies" + +docs-clean: ## Dump the existing built docs + @echo "=> Cleaning documentation build assets" + @rm -rf docs/_build + @echo "=> Removed existing documentation build assets" + +docs-serve: docs-clean docs-install ## Serve the docs locally + @echo "=> Serving documentation" + @$(ENV_PREFIX)sphinx-autobuild docs/ docs/_build/ -j auto --watch docs/ diff --git a/docs/requirements.txt b/docs/requirements.txt index 4072332b..0c3ef1f5 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -2,3 +2,4 @@ furo sphinx myst-parser sphinx-copybutton +sphinx-autobuild From 89651579bc993d92ef84ba4212b56a211521ae5d Mon Sep 17 00:00:00 2001 From: Jacob Coffee Date: Fri, 2 Aug 2024 11:17:30 -0500 Subject: [PATCH 2/3] chore: spacing --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 41273fe5..552e8ac4 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -PIP_COMMAND := $(shell command -v uv >/dev/null 2>&1 && echo "uv pip" || echo "pip") +PIP_COMMAND := $(shell command -v uv >/dev/null 2>&1 && echo "uv pip" || echo "pip") ENV_PREFIX = .venv/bin/ docs-install: ## Install docs dependencies From e4016e17ccccd743043f78ff3ecf6e4e8c4357bb Mon Sep 17 00:00:00 2001 From: Jacob Coffee Date: Fri, 9 Aug 2024 09:29:43 -0500 Subject: [PATCH 3/3] docs: containerify the local docs preview builds --- Dockerfile | 13 +++++++++++++ Makefile | 26 ++++++++++++++++---------- 2 files changed, 29 insertions(+), 10 deletions(-) create mode 100644 Dockerfile diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 00000000..dc63b810 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,13 @@ +FROM python:3.12-slim + +WORKDIR /app + +COPY docs/requirements.txt . +COPY docs/ docs/ + +RUN pip install uv +RUN uv pip install -r requirements.txt --system + +EXPOSE 8000 + +CMD ["sphinx-autobuild", "docs/", "docs/_build/", "--host", "0.0.0.0", "--port", "8000", "-j", "auto", "--watch", "docs/"] diff --git a/Makefile b/Makefile index 552e8ac4..2396b696 100644 --- a/Makefile +++ b/Makefile @@ -1,16 +1,22 @@ -PIP_COMMAND := $(shell command -v uv >/dev/null 2>&1 && echo "uv pip" || echo "pip") -ENV_PREFIX = .venv/bin/ +DOCKER_IMAGE_NAME := docs-server +DOCKER_CONTAINER_NAME := docs-container -docs-install: ## Install docs dependencies - @echo "=> Installing documentation dependencies" - @$(PIP_COMMAND) install -r docs/requirements.txt - @echo "=> Installed documentation dependencies" +.PHONY: docs-build docs-clean docs-serve -docs-clean: ## Dump the existing built docs +docs-build: + @echo "=> Building Docker image for documentation" + docker build -t $(DOCKER_IMAGE_NAME) -f Dockerfile . + +docs-clean: @echo "=> Cleaning documentation build assets" - @rm -rf docs/_build + docker run --rm -v $(PWD)/docs:/app/docs $(DOCKER_IMAGE_NAME) rm -rf /app/docs/_build @echo "=> Removed existing documentation build assets" -docs-serve: docs-clean docs-install ## Serve the docs locally +docs-serve: docs-build @echo "=> Serving documentation" - @$(ENV_PREFIX)sphinx-autobuild docs/ docs/_build/ -j auto --watch docs/ + docker run --name $(DOCKER_CONTAINER_NAME) -p 8000:8000 -v $(PWD)/docs:/app/docs $(DOCKER_IMAGE_NAME) + +docs-stop: + @echo "=> Stopping documentation server" + docker stop $(DOCKER_CONTAINER_NAME) + docker rm $(DOCKER_CONTAINER_NAME) \ No newline at end of file