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)
and with ./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
For Windows#
$ 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).
First run
./scripts/container.sh --clear-cache
.Then run
./scripts/container.sh --build
. This starts a local docker image calledarviz
.Finally, run the tests with
./scripts/container.sh --test
.
The ./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.
Run
./scripts/container.sh --clear-cache
because the cache generated locally is not valid for docker.Run
./scripts/container.sh --test
to 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
command.
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#
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 http://localhost:8888/?token=<token id>
.
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 doc/build/index.html
.
To update any file, go to the specific file(.md
, .rst
, or .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.