diff --git a/README.md b/README.md index da57046d4..7843b16dc 100644 --- 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 new file mode 100644 index 000000000..e2f450637 --- /dev/null +++ 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 new file mode 100644 index 000000000..ae2da115e --- /dev/null +++ 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 new file mode 100755 index 000000000..7e1dc0361 --- /dev/null +++ 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 new file mode 100755 index 000000000..a2362a59b --- /dev/null +++ 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 index 3838019a9..49cfc7f7e 100644 --- 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