contribute-building.md

Build the knowledgebase locally

You may want to build a local copy of the knowledgebase before creating a pull request. For example, you might want to check that your cross-referencing has worked as intended. This page explains how to do this.

The knowledgebase runs using Jupyter Books. If you have not used Jupyter Books before, please complete their tutorial on creating your first book before contributing. Note that Windows users will need to use Python 3.7.

First ensure you have Jupyter Books installed:

pip install -U jupyter-book

You can build the Jupyter Book by navigating to the root folder of the knowledgebase repo then running (if you make multiple builds, it is recommended to clean up before each new build):

jupyter-book clean .
jupyter-book build .

You can inspect the created book by opening the local HTML files in ca-knowledgebase/_build.

Building this site inside the Docker image

If you do not have all the software used in the knowledgebase installed locally, you can build the book inside the knowledgebase Docker image. You can launch this docker image by running the following commands in the root directory of the repo:

docker pull caknowledgebase/caknowledgebase:main
docker run -ti -p 8888:8888 -v $(pwd):/mnt/knowledgebase caknowledgebase/caknowledgebase:main

You will then be given a link to follow to open the Jupyter lab that the image runs. Once you've opened the lab, click 'Terminal' (under 'Other') then run:

cd /mnt/knowledgebase

You can then build the Jupyter book by running the same Jupyter book commands as above.