From 0db4009d30bf51c4452652a2b46456331e0fd3de Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Pi=C5=82atowski?= Date: Thu, 4 Mar 2021 13:49:14 +0100 Subject: [PATCH 1/9] add docker image --- docs/dev.dockerfile | 25 +++++++++++++++++++++++++ docs/docker-compose.yml | 9 +++++++++ docs/docker_run.sh | 9 +++++++++ docs/requirements.txt | 5 ++--- 4 files changed, 45 insertions(+), 3 deletions(-) create mode 100644 docs/dev.dockerfile create mode 100644 docs/docker-compose.yml create mode 100755 docs/docker_run.sh diff --git a/docs/dev.dockerfile b/docs/dev.dockerfile new file mode 100644 index 000000000..6b587f6ec --- /dev/null +++ b/docs/dev.dockerfile @@ -0,0 +1,25 @@ +FROM python:3.9 + +RUN apt-get update && apt-get install -y cmake libusb-1.0-0-dev build-essential cmake unzip pkg-config libjpeg-dev libpng-dev libtiff-dev libavcodec-dev libavformat-dev libswscale-dev libv4l-dev libxvidcore-dev libx264-dev libgtk-3-dev libatlas-base-dev gfortran python3-dev +RUN pip install -U pip numpy + +WORKDIR /libs +RUN wget -O opencv.zip https://github.com/opencv/opencv/archive/4.5.1.zip && unzip opencv.zip && mv opencv-4.5.1 opencv +RUN wget -O opencv_contrib.zip https://github.com/opencv/opencv_contrib/archive/4.5.1.zip && unzip opencv_contrib.zip && mv opencv_contrib-4.5.1 opencv_contrib +WORKDIR /libs/opencv/build +RUN cmake -D CMAKE_BUILD_TYPE=RELEASE \ + -D CMAKE_INSTALL_PREFIX=/usr/local \ + -D INSTALL_C_EXAMPLES=ON \ + -D INSTALL_PYTHON_EXAMPLES=ON \ + -D OPENCV_GENERATE_PKGCONFIG=ON \ + -D OPENCV_EXTRA_MODULES_PATH=/libs/opencv_contrib/modules \ + -D BUILD_EXAMPLES=ON .. && \ + make -j 8 && \ + make install + + +WORKDIR /app +ADD docs/requirements.txt docs/requirements.txt +RUN pip install -r docs/requirements.txt +ADD . . +CMD docs/docker_run.sh \ No newline at end of file diff --git a/docs/docker-compose.yml b/docs/docker-compose.yml new file mode 100644 index 000000000..63bbc7f5e --- /dev/null +++ b/docs/docker-compose.yml @@ -0,0 +1,9 @@ +services: + docs: + build: + dockerfile: docs/dev.dockerfile + context: .. + volumes: + - ./:/app/docs + ports: + - 8000:8000 \ No newline at end of file diff --git a/docs/docker_run.sh b/docs/docker_run.sh new file mode 100755 index 000000000..e846ca1c4 --- /dev/null +++ b/docs/docker_run.sh @@ -0,0 +1,9 @@ +#!/bin/bash + +set -e + +apt-get install -y doxygen python3-dev +rm -rf build +cmake -S . -B build -D DEPTHAI_BUILD_DOCS=ON -D DEPTHAI_PYTHON_BUILD_DOCS=ON +cmake --build build --parallel --target sphinx +python -m http.server 0.0.0.0:8000 \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt index 3838019a9..5c5a9f31c 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,9 +1,8 @@ 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 From bc66d1113043b3a32f728b3f545a1a731dcdbb9f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Pi=C5=82atowski?= Date: Fri, 5 Mar 2021 13:59:40 +0100 Subject: [PATCH 2/9] change to ubuntu:20.04 base image --- docs/dev.dockerfile | 26 +++++++------------------- docs/docker_run.sh | 8 +------- 2 files changed, 8 insertions(+), 26 deletions(-) diff --git a/docs/dev.dockerfile b/docs/dev.dockerfile index 6b587f6ec..02d903fe2 100644 --- a/docs/dev.dockerfile +++ b/docs/dev.dockerfile @@ -1,25 +1,13 @@ -FROM python:3.9 - -RUN apt-get update && apt-get install -y cmake libusb-1.0-0-dev build-essential cmake unzip pkg-config libjpeg-dev libpng-dev libtiff-dev libavcodec-dev libavformat-dev libswscale-dev libv4l-dev libxvidcore-dev libx264-dev libgtk-3-dev libatlas-base-dev gfortran python3-dev -RUN pip install -U pip numpy - -WORKDIR /libs -RUN wget -O opencv.zip https://github.com/opencv/opencv/archive/4.5.1.zip && unzip opencv.zip && mv opencv-4.5.1 opencv -RUN wget -O opencv_contrib.zip https://github.com/opencv/opencv_contrib/archive/4.5.1.zip && unzip opencv_contrib.zip && mv opencv_contrib-4.5.1 opencv_contrib -WORKDIR /libs/opencv/build -RUN cmake -D CMAKE_BUILD_TYPE=RELEASE \ - -D CMAKE_INSTALL_PREFIX=/usr/local \ - -D INSTALL_C_EXAMPLES=ON \ - -D INSTALL_PYTHON_EXAMPLES=ON \ - -D OPENCV_GENERATE_PKGCONFIG=ON \ - -D OPENCV_EXTRA_MODULES_PATH=/libs/opencv_contrib/modules \ - -D BUILD_EXAMPLES=ON .. && \ - make -j 8 && \ - make install +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 WORKDIR /app ADD docs/requirements.txt docs/requirements.txt -RUN pip install -r docs/requirements.txt +RUN python3 -m pip install -r docs/requirements.txt ADD . . +RUN cmake -S . -B build -D DEPTHAI_BUILD_DOCS=ON -D DEPTHAI_PYTHON_BUILD_DOCS=ON +RUN cmake --build build --parallel --target sphinx CMD docs/docker_run.sh \ No newline at end of file diff --git a/docs/docker_run.sh b/docs/docker_run.sh index e846ca1c4..2d3099f28 100755 --- a/docs/docker_run.sh +++ b/docs/docker_run.sh @@ -1,9 +1,3 @@ #!/bin/bash -set -e - -apt-get install -y doxygen python3-dev -rm -rf build -cmake -S . -B build -D DEPTHAI_BUILD_DOCS=ON -D DEPTHAI_PYTHON_BUILD_DOCS=ON -cmake --build build --parallel --target sphinx -python -m http.server 0.0.0.0:8000 \ No newline at end of file +python3 -m http.server 0.0.0.0:8000 \ No newline at end of file From 903c48f480bac9fa63da3c6d26cc034062f3e74c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Pi=C5=82atowski?= Date: Fri, 5 Mar 2021 16:46:04 +0100 Subject: [PATCH 3/9] make docs build work --- docs/dev.dockerfile | 6 +++--- docs/docker_run.sh | 8 +++++++- docs/update_docs.sh | 7 +++++++ 3 files changed, 17 insertions(+), 4 deletions(-) create mode 100755 docs/update_docs.sh diff --git a/docs/dev.dockerfile b/docs/dev.dockerfile index 02d903fe2..97f569a8d 100644 --- a/docs/dev.dockerfile +++ b/docs/dev.dockerfile @@ -2,12 +2,12 @@ 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 +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 . . -RUN cmake -S . -B build -D DEPTHAI_BUILD_DOCS=ON -D DEPTHAI_PYTHON_BUILD_DOCS=ON -RUN cmake --build build --parallel --target sphinx CMD docs/docker_run.sh \ No newline at end of file diff --git a/docs/docker_run.sh b/docs/docker_run.sh index 2d3099f28..7fdc7c9f2 100755 --- a/docs/docker_run.sh +++ b/docs/docker_run.sh @@ -1,3 +1,9 @@ #!/bin/bash -python3 -m http.server 0.0.0.0:8000 \ No newline at end of file +set -e + +./docs/update_docs.sh + +when-changed -r docs/source -c "bash /app/docs/update_docs.sh" & + +python3 -m http.server --bind 0.0.0.0 8000 --directory build/docs/sphinx \ No newline at end of file diff --git a/docs/update_docs.sh b/docs/update_docs.sh new file mode 100755 index 000000000..d4c34d397 --- /dev/null +++ b/docs/update_docs.sh @@ -0,0 +1,7 @@ +#!/bin/bash + +set -e + +rm -rf build +cmake -S . -B build -D DEPTHAI_BUILD_DOCS=ON -D DEPTHAI_PYTHON_BUILD_DOCS=ON +cmake --build build --parallel --target sphinx \ No newline at end of file From 7c18fed1bc974d266442760144872669ce3d7465 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Pi=C5=82atowski?= Date: Sun, 14 Mar 2021 13:35:06 +0100 Subject: [PATCH 4/9] linting --- docs/dev.dockerfile | 2 +- docs/docker-compose.yml | 2 +- docs/docker_run.sh | 2 +- docs/requirements.txt | 1 + docs/update_docs.sh | 2 +- 5 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/dev.dockerfile b/docs/dev.dockerfile index 97f569a8d..b3f226135 100644 --- a/docs/dev.dockerfile +++ b/docs/dev.dockerfile @@ -10,4 +10,4 @@ WORKDIR /app ADD docs/requirements.txt docs/requirements.txt RUN python3 -m pip install -r docs/requirements.txt ADD . . -CMD docs/docker_run.sh \ No newline at end of file +CMD docs/docker_run.sh diff --git a/docs/docker-compose.yml b/docs/docker-compose.yml index 63bbc7f5e..34d77d5dc 100644 --- a/docs/docker-compose.yml +++ b/docs/docker-compose.yml @@ -6,4 +6,4 @@ services: volumes: - ./:/app/docs ports: - - 8000:8000 \ No newline at end of file + - 8000:8000 diff --git a/docs/docker_run.sh b/docs/docker_run.sh index 7fdc7c9f2..360b26044 100755 --- a/docs/docker_run.sh +++ b/docs/docker_run.sh @@ -6,4 +6,4 @@ set -e when-changed -r docs/source -c "bash /app/docs/update_docs.sh" & -python3 -m http.server --bind 0.0.0.0 8000 --directory build/docs/sphinx \ No newline at end of file +python3 -m http.server --bind 0.0.0.0 8000 --directory build/docs/sphinx diff --git a/docs/requirements.txt b/docs/requirements.txt index 5c5a9f31c..49cfc7f7e 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,5 @@ Sphinx==3.4.3 +sphinx-tabs==1.3.0 sphinx-rtd-theme==0.5.0 git+https://github.com/VanDavv/rtd-redirects.git@3e7333898acad533b37c9de426f1f2ef258d756b breathe==4.26.0 diff --git a/docs/update_docs.sh b/docs/update_docs.sh index d4c34d397..809e5b88e 100755 --- a/docs/update_docs.sh +++ b/docs/update_docs.sh @@ -4,4 +4,4 @@ set -e rm -rf build cmake -S . -B build -D DEPTHAI_BUILD_DOCS=ON -D DEPTHAI_PYTHON_BUILD_DOCS=ON -cmake --build build --parallel --target sphinx \ No newline at end of file +cmake --build build --parallel --target sphinx From 03fb908d7458f28ac2803f2ce5d2639c6a9f40fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Pi=C5=82atowski?= Date: Tue, 16 Mar 2021 12:49:32 +0100 Subject: [PATCH 5/9] organize the docker files and optimize update script --- docs/docker-compose.yml | 2 +- docs/{ => docker}/dev.dockerfile | 2 +- docs/{ => docker}/docker_run.sh | 2 +- docs/{ => docker}/update_docs.sh | 4 ++-- 4 files changed, 5 insertions(+), 5 deletions(-) rename docs/{ => docker}/dev.dockerfile (92%) rename docs/{ => docker}/docker_run.sh (84%) rename docs/{ => docker}/update_docs.sh (64%) diff --git a/docs/docker-compose.yml b/docs/docker-compose.yml index 34d77d5dc..e2f450637 100644 --- a/docs/docker-compose.yml +++ b/docs/docker-compose.yml @@ -1,7 +1,7 @@ services: docs: build: - dockerfile: docs/dev.dockerfile + dockerfile: docs/docker/dev.dockerfile context: .. volumes: - ./:/app/docs diff --git a/docs/dev.dockerfile b/docs/docker/dev.dockerfile similarity index 92% rename from docs/dev.dockerfile rename to docs/docker/dev.dockerfile index b3f226135..ae2da115e 100644 --- a/docs/dev.dockerfile +++ b/docs/docker/dev.dockerfile @@ -10,4 +10,4 @@ WORKDIR /app ADD docs/requirements.txt docs/requirements.txt RUN python3 -m pip install -r docs/requirements.txt ADD . . -CMD docs/docker_run.sh +CMD docs/docker/docker_run.sh diff --git a/docs/docker_run.sh b/docs/docker/docker_run.sh similarity index 84% rename from docs/docker_run.sh rename to docs/docker/docker_run.sh index 360b26044..dbe83e251 100755 --- a/docs/docker_run.sh +++ b/docs/docker/docker_run.sh @@ -2,7 +2,7 @@ set -e -./docs/update_docs.sh +./docs/docker/update_docs.sh when-changed -r docs/source -c "bash /app/docs/update_docs.sh" & diff --git a/docs/update_docs.sh b/docs/docker/update_docs.sh similarity index 64% rename from docs/update_docs.sh rename to docs/docker/update_docs.sh index 809e5b88e..08bc678d6 100755 --- a/docs/update_docs.sh +++ b/docs/docker/update_docs.sh @@ -2,6 +2,6 @@ set -e -rm -rf build -cmake -S . -B build -D DEPTHAI_BUILD_DOCS=ON -D DEPTHAI_PYTHON_BUILD_DOCS=ON +rm -rf build/docs/sphinx +cmake -S . -B build -D DEPTHAI_BUILD_DOCS=ON -D DEPTHAI_PYTHON_BUILD_DOCS=ON -D ENABLE_PRECOMPILED_HEADERS=OFF cmake --build build --parallel --target sphinx From 453a5d9cfb50dfb32f6350c4a19a902d6ecbc687 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Pi=C5=82atowski?= Date: Tue, 16 Mar 2021 13:58:06 +0100 Subject: [PATCH 6/9] fix docker build & update --- docs/docker/docker_run.sh | 2 +- docs/docker/update_docs.sh | 3 +++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/docker/docker_run.sh b/docs/docker/docker_run.sh index dbe83e251..b584e8e87 100755 --- a/docs/docker/docker_run.sh +++ b/docs/docker/docker_run.sh @@ -4,6 +4,6 @@ set -e ./docs/docker/update_docs.sh -when-changed -r docs/source -c "bash /app/docs/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 index 08bc678d6..0976c19db 100755 --- a/docs/docker/update_docs.sh +++ b/docs/docker/update_docs.sh @@ -5,3 +5,6 @@ set -e rm -rf build/docs/sphinx cmake -S . -B build -D DEPTHAI_BUILD_DOCS=ON -D DEPTHAI_PYTHON_BUILD_DOCS=ON -D ENABLE_PRECOMPILED_HEADERS=OFF cmake --build build --parallel --target sphinx + +# fix missing index.css file +cp /app/docs/source/_static/css/* /app/build/docs/sphinx/_static/css From 4b1275397bc99144d23f75788c115b217cf326c7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Pi=C5=82atowski?= Date: Wed, 17 Mar 2021 14:08:34 +0100 Subject: [PATCH 7/9] update README.md, add building instuctions for docs --- README.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/README.md b/README.md index da57046d4..31402958c 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,38 @@ 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 + + ``` + cmake -S . -B build -D DEPTHAI_BUILD_DOCS=ON -D DEPTHAI_PYTHON_BUILD_DOCS=ON -D ENABLE_PRECOMPILED_HEADERS=OFF + 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, these commnads will + have to be run again to build updated website + + ## Installation Prebuilt wheels are available in [Luxonis repository](https://artifacts.luxonis.com/artifactory/luxonis-python-snapshot-local/) From 0ceff325a99aa649a3659d567f3830297e695e07 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Pi=C5=82atowski?= Date: Wed, 17 Mar 2021 14:55:18 +0100 Subject: [PATCH 8/9] remove unneeded flag --- README.md | 2 +- docs/docker/update_docs.sh | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 31402958c..e92e199d5 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ Documentation is available over at [Luxonis DepthAI API](https://docs.luxonis.co Then run the following commands to build the docs website ``` - cmake -S . -B build -D DEPTHAI_BUILD_DOCS=ON -D DEPTHAI_PYTHON_BUILD_DOCS=ON -D ENABLE_PRECOMPILED_HEADERS=OFF + 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 ``` diff --git a/docs/docker/update_docs.sh b/docs/docker/update_docs.sh index 0976c19db..d6fed0308 100755 --- a/docs/docker/update_docs.sh +++ b/docs/docker/update_docs.sh @@ -3,7 +3,7 @@ set -e rm -rf build/docs/sphinx -cmake -S . -B build -D DEPTHAI_BUILD_DOCS=ON -D DEPTHAI_PYTHON_BUILD_DOCS=ON -D ENABLE_PRECOMPILED_HEADERS=OFF +cmake -S . -B build -D DEPTHAI_BUILD_DOCS=ON -D DEPTHAI_PYTHON_BUILD_DOCS=ON cmake --build build --parallel --target sphinx # fix missing index.css file From bb8d8b945336d977c076ef84a830313b9df99901 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Pi=C5=82atowski?= Date: Wed, 17 Mar 2021 15:11:47 +0100 Subject: [PATCH 9/9] Update documentation and speed up the updates --- README.md | 12 ++++++++++-- docs/docker/docker_run.sh | 2 ++ docs/docker/update_docs.sh | 2 -- 3 files changed, 12 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index e92e199d5..7843b16dc 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,8 @@ Documentation is available over at [Luxonis DepthAI API](https://docs.luxonis.co 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 @@ -38,8 +40,14 @@ Documentation is available over at [Luxonis DepthAI API](https://docs.luxonis.co Then open [http://localhost:8000](http://localhost:8000). - This will build documentation based on current sources, so if some new changes will be made, these commnads will - have to be run again to build updated website + 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 diff --git a/docs/docker/docker_run.sh b/docs/docker/docker_run.sh index b584e8e87..7e1dc0361 100755 --- a/docs/docker/docker_run.sh +++ b/docs/docker/docker_run.sh @@ -2,6 +2,8 @@ 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" & diff --git a/docs/docker/update_docs.sh b/docs/docker/update_docs.sh index d6fed0308..a2362a59b 100755 --- a/docs/docker/update_docs.sh +++ b/docs/docker/update_docs.sh @@ -2,8 +2,6 @@ set -e -rm -rf build/docs/sphinx -cmake -S . -B build -D DEPTHAI_BUILD_DOCS=ON -D DEPTHAI_PYTHON_BUILD_DOCS=ON cmake --build build --parallel --target sphinx # fix missing index.css file