Developing in Docker#
We have provided a Dockerfile which helps for isolating build problems, and local development.
Install Docker for your operating system, clone this repo. Docker will generate an environment with your local copy of
arviz with all the packages in Dockerfile.
container.sh & container.ps1#
Predefined docker commands can be run with a
./scripts/container.sh (on Linux and macOS)
./scripts/container.ps1. The scripts enable developers easily to call predefined docker commands.
Users can use one or multiple flags.
They are executed in the following order: clear-cache, build, test, docs, shell, notebook, lab
For Linux and macOS#
$ ./scripts/container.sh --clear-cache $ ./scripts/container.sh --build $ ./scripts/container.sh --test $ ./scripts/container.sh --docs $ ./scripts/container.sh --shell $ ./scripts/container.sh --notebook $ ./scripts/container.sh --lab
$ powershell.exe -File ./scripts/container.ps1 --clear-cache $ powershell.exe -File ./scripts/container.ps1 --build $ powershell.exe -File ./scripts/container.ps1 --test $ powershell.exe -File ./scripts/container.ps1 --docs $ powershell.exe -File ./scripts/container.ps1 --shell $ powershell.exe -File ./scripts/container.ps1 --notebook $ powershell.exe -File ./scripts/container.ps1 --lab
Testing in Docker#
Testing the code using docker consists of executing the same file(
./scripts/container.ps1) 3 times (you may need root privileges to run it).
./scripts/container.sh --build. This starts a local docker image called
Finally, run the tests with
./scripts/container.sh --build command needs to be executed only once to build the docker image. If you have already built the docker image, and want to test your new changes, then it is a 2 step process.
./scripts/container.sh --clear-cachebecause the cache generated locally is not valid for docker.
./scripts/container.sh --testto test with docker.
NOTE: If you run into errors due to
__pycache__ files (i.e. while testing in
docker after testing locally or installing with pip after testing with
docker), try running
./scripts/container.sh --clear-cache before the errored
Using the Docker image interactively#
Once the Docker image is built with
./scripts/container.sh --build, interactive containers can also be run. Therefore, code can be edited and executed using the docker container, but modifying directly the working directory of the host machine.
For Linux and macOS#
To start a bash shell inside Docker, run:
$ docker run --mount type=bind,source="$(pwd)",target=/opt/arviz/ -it arviz bash
Alternatively, to start a jupyter notebook, there are two steps, first run:
$ docker run --mount type=bind,source="$(pwd)",target=/opt/arviz/ --name jupyter-dock -it -d -p 8888:8888 arviz $ docker exec jupyter-dock bash -c "pip install jupyter" $ docker exec -it jupyter-dock bash -c "jupyter notebook --ip 0.0.0.0 --no-browser --allow-root"
For Windows, use %CD% on cmd.exe and $pwd.Path on powershell.
$ docker run --mount type=bind,source=%CD%,target=/opt/arviz/ -it arviz bash
For running a jupyter notebook, run:
$ docker run --mount type=bind,source=%CD%,target=/opt/arviz/ --name jupyter-dock -it -d -p 8888:8888 arviz $ docker exec jupyter-dock bash -c "pip install jupyter" $ docker exec -it jupyter-dock bash -c "jupyter notebook --ip 0.0.0.0 --no-browser --allow-root"
This will output something similar to
http://(<docker container id> or <ip>):8888/?token=<token id>, and can be accessed at
Building documentation with Docker#
The documentation can be built with Docker by running
./scripts/container.sh --docs. The
./scripts/container.sh --build needs to be executed once before running the doc build command.
The docker image contains by default all dependencies needed
for building the documentation. After having build the docs in the Docker
container, they can be checked at
doc/build and viewed in the browser from
To update any file, go to the specific file(
.ipynb) and make your changes. In order to check the results, you can either check the Previewing doc changes or rebuild the docs with Docker. For the latter option, You need to only rebuild the docs, using the same command
./scripts/container.sh --docs. The resulting docs will be saved in the
doc/build directory as HTML files. Open your corresponding file and check the results. You wil also need to rebuild the docker image if extensions and dependencies were added or changed.