Build Sphinx docs locally with the ReadTheDocs Docker container

build_sphinx_docs_with_readthedocs_container.Dockerfile

FROM readthedocs/build:latest
## Install system packages
#RUN pip install -U pip
## Install latest pip
#RUN curl -SL https://bootstrap.pypa.io/get-pip.py > get-pip.py
#RUN python ./get-pip.py

## Install dotfiles
ARG uid=1000
ARG user="app"
ARG home="/home/${user}"
ARG __wrk="${home}/-wrk"
ARG workon_home="${__wrk}/-ve37"
ARG venvname="appname"
ARG project="${__wrk}/${venvname}"
ARG virtual_env="${workon_home}/${venvname}"

USER root
RUN useradd ${user} -d ${home} -s /usr/bin/bash -u ${uid} -m

USER ${user}
RUN mkdir -p ${virtual_env} \
    && ln -s ${project} ${virtual_env}/src
VOLUME ${project}

USER 1000

# COPY --chown=${user} \
COPY --chown=1000:1000 \
     requirements.txt requirements_dev.txt ${__wrk}/
RUN python3 -m venv ${virtual_env} \
    && ${virtual_env}/bin/pip install \
    -r ${__wrk}/requirements_dev.txt \
    -r ${__wrk}/requirements.txt

CMD ["/bin/bash"]

build_sphinx_docs_with_readthedocs_container.Makefile

# ...
_SRC=$HOME/-wrk
project=
appname=appname
venvname=${appname}
virtual_env=$VIRTUAL_ENV
# ...

docker-build-rtdocs:
	cp requirements.txt requirements_dev.txt docs/
	cd docs/ && docker build . -t turnernet/docs:latest

docker-run-docs-rtd: docker-run-rtdocs
docker-run-rtdocs:
	docker run --rm \
		-v "${_SRC}":${project}:z \
		-t ${appname}/docs:latest bash -c "\
			source "${virtual_env}/bin/activate" && \
			cd '${project}/${appname}' && \
			make -C docs html singlehtml latexpdf && \
			ls -la docs/_build docs/_build/latex/${appname}.pdf"
	@# make html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latexpdf text man texinfo info gettext changes xml pseudoxml linkcheck
	$(MAKE) docs-copy-built

DATESTR:=$(shell date +'%Y-%m-%dT%H:%M')
PDFNAME=${venvname}.pdf
PDFNAMEDATE=${venvname}-${DATESTR}.pdf

docs-copy-built:
	cd docs/_build && rsync -aAX latex/${PDFNAME} html/_static/${PDFNAMEDATE}
	cd docs/_build/html/_static \
		&& rm ${PDFNAME} \
		&& ln -s ${PDFNAMEDATE} ${PDFNAME}
	rsync -aAX docs/_build/singlehtml/ docs/_build/html/singlehtml


DOCSREVDIR=${BUILDDIRHTML}
DOCS_REV_TXT=${DOCSREVDIR}/_gitrev.txt
docs_write_rev_txt:
	git -C $$PWD rev-parse --short HEAD > '${DOCS_REV_TXT}'
	cat '${DOCS_REV_TXT}'

docs-notify:
	$(shell (hash notify-send \
		&& notify-send -t 30000 "docs build complete." \
        '$(shell pwd)') || true)

docs:
	$(MAKE) docker-run-rtdocs
	$(MAKE) docs_write_rev_txt
	$(MAKE) docs-notify

DOCS_GIT_HTML_BRANCH=gh-pages
BUILDDIRHTML=docs/_build/html
gh-pages:
	# Push docs to gh-pages branch with a .nojekyll file
	ghp-import -n -b '${DOCS_GIT_HTML_BRANCH}' -p '${BUILDDIRHTML}' \
		-m 'DOC,RLS: :books: docs built from: $(shell cat ${DOCS_REV_TXT})'
	git --no-pager log -n3 --stat '${DOCS_GIT_HTML_BRANCH}'

gh-pages-push:
	git push origin gh-pages:gh-pages

push:
	git push