This project uses a Dockerfile to automate git cloning the repo for easily testing the compatibility of various docSkimmer theme and MkDocs versions (either current, or otherwise specified) without having to install either locally.
$ sudo systemctl start docker
$ sudo docker build . -t my-docskimmer -f Dockerfile
$ sudo docker run -p 8000:8080 my-docskimmer- Browse to http:https://0.0.0.0:8000/mkdocs-docskimmer/ 🎉
An excerpt of successful build output is shown below:
(using MkDocs v1.5.3 with docSkimmer theme 'master' branch)
$ sudo docker build . -t my-docskimmer -f Dockerfile
[+] Building 6.9s (11/11) FINISHED
=> [internal] load .dockerignore 0.4s
=> => transferring context: 2B 0.0s
=> [internal] load build definition from Dockerfile 0.3s
=> => transferring dockerfile: 467B 0.0s
=> [internal] load metadata for docker.io/library/python:3.8.2 0.9s
=> [internal] load build context 0.2s
=> => transferring context: 618B 0.0s
=> [1/6] FROM docker.io/library/python:3.8.2@sha256:8c98602bf4f4b2f9b6bd8def396d5149821c59f8a69e74 0.0s
=> CACHED [2/6] WORKDIR /build 0.0s
=> CACHED [3/6] COPY requirements.txt . 0.0s
=> CACHED [4/6] RUN pip install --no-cache-dir -r requirements.txt 0.0s
=> [5/6] COPY docs_local-updates ./my-project/docs 1.0s
=> [6/6] COPY mkdocs.yml ./my-project/mkdocs.yml 0.8s
=> exporting to image 2.4s
=> => exporting layers 2.2s
=> => writing image sha256:0274aee1e791ec0f0af2df18b3df607c41b0640a9fe2e7af0cbed8d8e24a94ac 0.1s
=> => naming to docker.io/library/my-docskimmer 0.1s
## NOTE: warnings (below) do not break the build
$ sudo docker run -p 8000:8080 my-docskimmer
WARNING - Config value 'dev_addr': The use of the IP address '0.0.0.0' suggests a production environment or the use of a proxy to connect to the MkDocs server. However, the MkDocs' server is intended for local development purposes only. Please use a third party production-ready server instead.
INFO - Building documentation...
INFO - Cleaning site directory
INFO - Documentation built in 0.29 seconds
INFO - [00:38:37] Watching paths for changes: 'my-project/docs', 'my-project/mkdocs.yml'
INFO - [00:38:37] Serving on http:https://0.0.0.0:8080/
INFO - [00:38:39] Browser connected: http:https://0.0.0.0:8000/
## ...- start Docker:
$ sudo systemctl start docker; - build and tag the Docker image 'my-docskimmer':
$ sudo docker build . -t my-docskimmer -f Dockerfile;- NOTE: run this in the same directory as the Dockerfile)
- run Docker image 'my-docskimmer':
$ sudo docker run -p 8000:8080 my-docskimmer;- this maps port 8080 in the container to port 8000 on the Docker host
- browse to http:https://0.0.0.0:8000/mkdocs-docskimmer/
- see
view-source:http:https://0.0.0.0:8000/mkdocs-docskimmer/for version numbers of both the docSkimmer theme and MkDocs
- see
- line 3 of the Dockerfile: Specify the Python version (for compatibility with MkDocs - refer to user guide;
- line 1 of requirements.txt: Specify the MkDocs version - (latest: v1.5.3 - at time of writing);
-
line 2 of requirements.txt: Specify the tag, release/version, or branch of docSkimmer theme - (note:
masterbranch contains the latest, unreleased changes since v0.4.0)examples:
- install latest changes (ie. 'master' branch'):
pip install git+https://github.com/hfagerlund/mkdocs-docskimmer.git@master- install version 0.3.1:
pip install git+https://github.com/hfagerlund/[email protected]- install experimental branch 'issue-17_fix-config-value':
pip install git+https://github.com/hfagerlund/mkdocs-docskimmer.git@issue-17_fix-config-value
Docker commands [+]
- List Docker images (eg. 'my-docskimmer'):
$ sudo docker images- List Docker containers:
$ sudo docker container ls -a- Remove Docker image 'my-docskimmer' once finished:
$ sudo docker rmi -f my-docskimmer- Debug Docker build (display output of commands not loaded from cache):
$ sudo docker build --progress=plain --no-cache . -t my-docskimmer -f Dockerfile- Stop Docker:
$ sudo systemctl stop docker- Check whether Docker is running:
$ sudo systemctl status dockerCopyright (c) 2023 Heini Fagerlund. Licensed under the BSD-3-Clause license.