Add docker image that allows to run docs in development mode (luxonis#157)

VanDavv · web-flow · commit 1fbbade268a5 · 2021-03-17T15:59:26.000+01:00
* add docker image

* change to ubuntu:20.04 base image

* make docs build work

* linting

* organize the docker files and optimize update script

* fix docker build &amp; update

* update README.md, add building instuctions for docs

* remove unneeded flag

* Update documentation and speed up the updates
diff --git a/README.md b/README.md
@@ -10,6 +10,46 @@ Python bindings for C++ depthai-core library
 
 Documentation is available over at [Luxonis DepthAI API](https://docs.luxonis.com/projects/api/en/latest/)
 
+### Building documentation
+
+- **Using [Docker](https://docs.docker.com/) (with [Docker Compose](https://docs.docker.com/compose/install/))**
+
+     ```
+     cd docs
+     docker-compose build
+     docker-compose up
+     ```
+  
+     Then open [http://localhost:8000](http://localhost:8000).
+     
+     This docker container will watch changes in the `docs/source` directory and rebuild the docs automatically
+
+- **Linux**
+     
+     First, please install the required [dependencies](#Dependencies)
+  
+     Then run the following commands to build the docs website
+  
+     ```
+     python3 -m pip install -U pip
+     python3 -m pip install -r docs/requirements.txt
+     cmake -S . -B build -D DEPTHAI_BUILD_DOCS=ON -D DEPTHAI_PYTHON_BUILD_DOCS=ON
+     cmake --build build --parallel --target sphinx
+     python3 -m http.server --bind 0.0.0.0 8000 --directory build/docs/sphinx
+     ```
+  
+     Then open [http://localhost:8000](http://localhost:8000).
+
+     This will build documentation based on current sources, so if some new changes will be made, run this command
+     in a new terminal window to update the website source
+  
+     ```
+     cmake --build build --parallel --target sphinx
+     ```
+  
+     Then refresh your page - it should load the updated website that was just built
+  
+
 ## Installation
 
 Prebuilt wheels are available in [Luxonis repository](https://artifacts.luxonis.com/artifactory/luxonis-python-snapshot-local/)
diff --git a/docs/docker-compose.yml b/docs/docker-compose.yml
@@ -0,0 +1,9 @@
+services:
+  docs:
+    build:
+      dockerfile: docs/docker/dev.dockerfile
+      context: ..
+    volumes:
+      - ./:/app/docs
+    ports:
+      - 8000:8000
diff --git a/docs/docker/dev.dockerfile b/docs/docker/dev.dockerfile
@@ -0,0 +1,13 @@
+FROM ubuntu:20.04
+
+ARG DEBIAN_FRONTEND=noninteractive
+RUN apt-get update && apt-get install -y libusb-1.0-0-dev clang python3-opencv python3-pip clang-11 doxygen cmake git
+RUN python3 -m pip install -U pip numpy when-changed
+
+ENV CC clang-10
+ENV CXX clang++-10
+WORKDIR /app
+ADD docs/requirements.txt docs/requirements.txt
+RUN python3 -m pip install -r docs/requirements.txt
+ADD . .
+CMD docs/docker/docker_run.sh
diff --git a/docs/docker/docker_run.sh b/docs/docker/docker_run.sh
@@ -0,0 +1,11 @@
+#!/bin/bash
+
+set -e
+
+cmake -S . -B build -D DEPTHAI_BUILD_DOCS=ON -D DEPTHAI_PYTHON_BUILD_DOCS=ON
+
+./docs/docker/update_docs.sh
+
+when-changed -r docs/source -c "bash /app/docs/docker/update_docs.sh" &
+
+python3 -m http.server --bind 0.0.0.0 8000 --directory build/docs/sphinx
diff --git a/docs/docker/update_docs.sh b/docs/docker/update_docs.sh
@@ -0,0 +1,8 @@
+#!/bin/bash
+
+set -e
+
+cmake --build build --parallel --target sphinx
+
+# fix missing index.css file
+cp /app/docs/source/_static/css/* /app/build/docs/sphinx/_static/css
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,9 +1,9 @@
 Sphinx==3.4.3
 sphinx-tabs==1.3.0
 sphinx-rtd-theme==0.5.0
-git+git://github.com/VanDavv/rtd-redirects.git@3e7333898acad533b37c9de426f1f2ef258d756b
+git+https://github.com/VanDavv/rtd-redirects.git@3e7333898acad533b37c9de426f1f2ef258d756b
 breathe==4.26.0
-git+git://github.com/luxonis/pybind11_mkdoc.git@master
+git+https://github.com/luxonis/pybind11_mkdoc.git@master
 Sphinx-Substitution-Extensions==2020.9.30.0
 sphinx-autopackagesummary==1.3
 autodocsumm==0.2.2
