Improve docs building

Dockerfile

@@ -1,6 +1,4 @@
-FROM python:3.8.18-slim-bookworm
-
-ARG PIP_INDEX_URL
+FROM python:3.11.6-slim-bookworm
 
 # gcc is for regex package build (regex is black dependency), see https://github.com/psf/black/issues/1112
 # libffi-dev is for poetry.
@@ -10,14 +8,15 @@ RUN apt-get update && \
 
 # install urllib v1.x manually to avoid 'strict' attribute error
 RUN pip3 install "urllib3<2"
-RUN pip3 install poetry==1.1.12
+ARG POETRY_VERSION
+RUN pip3 install poetry==${POETRY_VERSION}
 
 WORKDIR /cybsi_cloud_sdk
 
 # dependencies for poetry install
 COPY poetry.lock pyproject.toml README.md ./
 COPY ./cybsi/__version__.py ./cybsi/py.typed ./cybsi/
 
-RUN poetry install
+RUN poetry install --with docs
 
 ADD . /cybsi_cloud_sdk

Makefile

@@ -6,6 +6,7 @@ DOCKER_IMAGE := cybsi/cybsi-cloud-sdk
 DOCKER_TAG ?= latest
 VENV_DIR ?= .venv
 SOURCE_DIRS := cybsi examples # TODO: add tests
+POETRY_VERSION := 1.7.0
 
 # If the first argument is "bump-version"...
 ifeq (bump-version,$(firstword $(MAKECMDGOALS)))
@@ -32,7 +33,7 @@ build-docs:
 
 .PHONY: image-build
 image-build:
-	docker build $(DOCKER_BUILD_FLAGS) --tag "$(DOCKER_IMAGE):$(DOCKER_TAG)" "$(ROOT_DIR)"
+	docker build $(DOCKER_BUILD_FLAGS) --build-arg POETRY_VERSION=${POETRY_VERSION} --tag "$(DOCKER_IMAGE):$(DOCKER_TAG)" "$(ROOT_DIR)"
 
 .PHONY: image-clean
 image-clean: ### Remove last version of the images.
@@ -62,8 +63,15 @@ docker-clean:
 .PHONY: tools
 tools: #### Install tools needed for development.
 	pip3 install "urllib3<2"
-	pip3 install poetry==1.1.12
-	poetry install
+	pip3 install poetry==${POETRY_VERSION}
+	poetry self add poetry-plugin-export # add plugin for poetry export to requirements.txt
+	poetry install --with docs,docs-dev
+
+.PHONY: update-docs-dependencies
+update-docs-dependencies: #### Upgrade pinned docks dependencies.
+	poetry export -f requirements.txt --without-hashes --only docs -o ${DOCS_DIR}/requirements.in
+	make -C ${DOCS_DIR} update-dependencies
+
 
 .PHONY: bump-version
 bump-version:

docs/Makefile

@@ -58,4 +58,8 @@ linkcheck:
 doctest:
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+.PHONY: update-dependencies
+update-dependencies:
+	pip-compile --strip-extras -o requirements.txt requirements.in

docs/requirements.in

@@ -0,0 +1,68 @@
+accessible-pygments==0.0.4 ; python_version >= "3.8" and python_version < "3.12"
+alabaster==0.7.13 ; python_version >= "3.8" and python_version < "3.12"
+anyio==4.0.0 ; python_version >= "3.8" and python_version < "3.12"
+apeye-core==1.1.4 ; python_version >= "3.8" and python_version < "3.12"
+apeye==1.4.1 ; python_version >= "3.8" and python_version < "3.12"
+autodocsumm==0.2.11 ; python_version >= "3.8" and python_version < "3.12"
+babel==2.13.1 ; python_version >= "3.8" and python_version < "3.12"
+beautifulsoup4==4.12.2 ; python_version >= "3.8" and python_version < "3.12"
+cachecontrol[filecache]==0.13.1 ; python_version >= "3.8" and python_version < "3.12"
+certifi==2023.7.22 ; python_version >= "3.8" and python_version < "3.12"
+charset-normalizer==3.3.2 ; python_version >= "3.8" and python_version < "3.12"
+click==8.1.7 ; python_version >= "3.8" and python_version < "3.12"
+colorama==0.4.6 ; python_version >= "3.8" and python_version < "3.12" and (sys_platform == "win32" or platform_system == "Windows")
+consolekit==1.5.1 ; python_version >= "3.8" and python_version < "3.12"
+cssutils==2.9.0 ; python_version >= "3.8" and python_version < "3.12"
+deprecation-alias==0.3.2 ; python_version >= "3.8" and python_version < "3.12"
+deprecation==2.1.0 ; python_version >= "3.8" and python_version < "3.12"
+dict2css==0.3.0 ; python_version >= "3.8" and python_version < "3.12"
+docutils==0.16 ; python_version >= "3.8" and python_version < "3.12"
+domdf-python-tools==3.7.0 ; python_version >= "3.8" and python_version < "3.12"
+enum-tools==0.11.0 ; python_version >= "3.8" and python_version < "3.12"
+exceptiongroup==1.1.3 ; python_version >= "3.8" and python_version < "3.11"
+filelock==3.13.1 ; python_version >= "3.8" and python_version < "3.12"
+h11==0.14.0 ; python_version >= "3.8" and python_version < "3.12"
+html5lib==1.1 ; python_version >= "3.8" and python_version < "3.12"
+httpcore==0.16.3 ; python_version >= "3.8" and python_version < "3.12"
+httpx==0.23.1 ; python_version >= "3.8" and python_version < "3.12"
+idna==3.4 ; python_version >= "3.8" and python_version < "3.12"
+imagesize==1.4.1 ; python_version >= "3.8" and python_version < "3.12"
+importlib-metadata==6.8.0 ; python_version >= "3.8" and python_version < "3.9"
+jinja2==3.1.2 ; python_version >= "3.8" and python_version < "3.12"
+lockfile==0.12.2 ; python_version >= "3.8" and python_version < "3.12"
+markupsafe==2.1.3 ; python_version >= "3.8" and python_version < "3.12"
+mistletoe==1.2.1 ; python_version >= "3.8" and python_version < "3.12"
+msgpack==1.0.7 ; python_version >= "3.8" and python_version < "3.12"
+natsort==8.4.0 ; python_version >= "3.8" and python_version < "3.12"
+packaging==23.2 ; python_version >= "3.8" and python_version < "3.12"
+platformdirs==3.11.0 ; python_version >= "3.8" and python_version < "3.12"
+pydata-sphinx-theme==0.13.3 ; python_version >= "3.8" and python_version < "3.12"
+pygments==2.16.1 ; python_version >= "3.8" and python_version < "3.12"
+pytz==2023.3.post1 ; python_version >= "3.8" and python_version < "3.9"
+requests==2.31.0 ; python_version >= "3.8" and python_version < "3.12"
+rfc3986[idna2008]==1.5.0 ; python_version >= "3.8" and python_version < "3.12"
+ruamel-yaml-clib==0.2.8 ; platform_python_implementation == "CPython" and python_version < "3.12" and python_version >= "3.8"
+ruamel-yaml==0.18.5 ; python_version >= "3.8" and python_version < "3.12"
+setuptools==68.2.2 ; python_version >= "3.8" and python_version < "3.12"
+six==1.16.0 ; python_version >= "3.8" and python_version < "3.12"
+sniffio==1.3.0 ; python_version >= "3.8" and python_version < "3.12"
+snowballstemmer==2.2.0 ; python_version >= "3.8" and python_version < "3.12"
+soupsieve==2.5 ; python_version >= "3.8" and python_version < "3.12"
+sphinx-autodoc-typehints==1.11.1 ; python_version >= "3.8" and python_version < "3.12"
+sphinx-book-theme==1.0.1 ; python_version >= "3.8" and python_version < "3.12"
+sphinx-jinja2-compat==0.1.1 ; python_version >= "3.8" and python_version < "3.12"
+sphinx-prompt==1.5.0 ; python_version >= "3.8" and python_version < "3.12"
+sphinx-tabs==3.2.0 ; python_version >= "3.8" and python_version < "3.12"
+sphinx-toolbox==2.16.0 ; python_version >= "3.8" and python_version < "3.12"
+sphinx==4.2.0 ; python_version >= "3.8" and python_version < "3.12"
+sphinxcontrib-applehelp==1.0.4 ; python_version >= "3.8" and python_version < "3.12"
+sphinxcontrib-devhelp==1.0.2 ; python_version >= "3.8" and python_version < "3.12"
+sphinxcontrib-htmlhelp==2.0.1 ; python_version >= "3.8" and python_version < "3.12"
+sphinxcontrib-jsmath==1.0.1 ; python_version >= "3.8" and python_version < "3.12"
+sphinxcontrib-qthelp==1.0.3 ; python_version >= "3.8" and python_version < "3.12"
+sphinxcontrib-serializinghtml==1.1.5 ; python_version >= "3.8" and python_version < "3.12"
+tabulate==0.8.10 ; python_version >= "3.8" and python_version < "3.12"
+typing-extensions==4.8.0 ; python_version >= "3.8" and python_version < "3.12"
+urllib3==2.0.7 ; python_version >= "3.8" and python_version < "3.12"
+webencodings==0.5.1 ; python_version >= "3.8" and python_version < "3.12"
+zipp==3.17.0 ; python_version >= "3.8" and python_version < "3.9"