Documented majority of bindings, integrated sphinx, added pybind11-mkdoc

luxonis · Mar 1, 2021 · 181e28b · 181e28b
1 parent 20c4c28
commit 181e28b
Show file tree

Hide file tree

Showing 57 changed files with 1,014 additions and 944 deletions.
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -1,4 +1,4 @@
-name: Python Wheel CI/CD
+name: Depthai Python CI/CD
 
 # Controls when the action will run. Triggers the workflow on push
 
@@ -24,8 +24,41 @@ on:
 # A workflow run is made up of one or more jobs that can run sequentially or in parallel
 jobs:
 
+  # Job which builds docstrings for the rest of the wheel builds
+  build-docstrings:
+    runs-on: macos-latest
+    steps:
+      - name: Cache .hunter folder
+        uses: actions/cache@v2
+        with:
+          path: ~/.hunter/
+          key: hunter-clang
+      - uses: actions/checkout@v2
+        with:
+          submodules: 'recursive'
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with: 
+          python-version: 3.8
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          brew install libusb
+          python -m pip install git+git://github.com/luxonis/pybind11_mkdoc.git@master
+      - name: Configure project
+        run: cmake -S . -B build -DDEPTHAI_PYTHON_BUILD_DOCSTRINGS=ON -DDEPTHAI_PYTHON_FORCE_DOCSTRINGS=ON -DDEPTHAI_PYTHON_DOCSTRINGS_OUTPUT="$PWD/docstrings/depthai_python_docstring.hpp"
+      - name: Build target 'pybind11_mkdoc'
+        run: cmake --build build --parallel --target pybind11_mkdoc
+      - name: Upload docstring artifacts
+        uses: actions/upload-artifact@v2
+        with:
+          name: docstrings
+          path: docstrings/
+          retention-days: 1
+
   # This job builds wheels for armhf arch (RPi)
   build-linux-armhf:
+    needs: build-docstrings
     runs-on: luxonis-armhf
     container: 
       image: registry.gitlab.com/luxonis/depthai-crosscompile/debian-buster
@@ -38,6 +71,14 @@ jobs:
       - uses: actions/checkout@v2
         with:
           submodules: 'recursive'
+
+      - uses: actions/download-artifact@v2
+        with:
+          name: 'docstrings'
+          path: docstrings
+      - name: Specify docstring to use while building the wheel
+        run: echo "DEPTHAI_PYTHON_DOCSTRINGS_INPUT=$PWD/docstrings/depthai_python_docstring.hpp" >> $GITHUB_ENV
+
       - name: Append build hash if not a tagged commit
         if: startsWith(github.ref, 'refs/tags/v') != true
         run: echo "BUILD_COMMIT_HASH=${{github.sha}}" >> $GITHUB_ENV
@@ -53,6 +94,7 @@ jobs:
 
   # This job builds wheels for Windows x86_64 arch
   build-windows-x86_64:
+    needs: build-docstrings
     runs-on: windows-latest
     strategy:
       matrix:
@@ -67,6 +109,14 @@ jobs:
       - uses: actions/checkout@v2
         with:
           submodules: 'recursive'
+
+      - uses: actions/download-artifact@v2
+        with:
+          name: 'docstrings'
+          path: docstrings
+      - name: Specify docstring to use while building the wheel
+        run: echo "DEPTHAI_PYTHON_DOCSTRINGS_INPUT=$PWD/docstrings/depthai_python_docstring.hpp" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v2
         with: 
@@ -88,6 +138,7 @@ jobs:
 
   # This job builds wheels for macOS x86_64 arch
   build-macos-x86_64:
+    needs: build-docstrings
     runs-on: macos-latest
     strategy:
       matrix:
@@ -101,6 +152,14 @@ jobs:
       - uses: actions/checkout@v2
         with:
           submodules: 'recursive'
+
+      - uses: actions/download-artifact@v2
+        with:
+          name: 'docstrings'
+          path: docstrings
+      - name: Specify docstring to use while building the wheel
+        run: echo "DEPTHAI_PYTHON_DOCSTRINGS_INPUT=$PWD/docstrings/depthai_python_docstring.hpp" >> $GITHUB_ENV
+
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v2
         with: 
@@ -127,6 +186,7 @@ jobs:
 
   # This job builds wheels for x86_64 arch
   build-linux-x86_64:
+    needs: build-docstrings
     runs-on: ubuntu-latest
     container:
       image: quay.io/pypa/manylinux2014_x86_64
@@ -149,6 +209,14 @@ jobs:
           ln -s /opt/python/cp38-cp38/bin/cmake /bin/
       - name: Create folder structure
         run: mkdir -p wheelhouse/audited/
+
+      - uses: actions/download-artifact@v2
+        with:
+          name: 'docstrings'
+          path: docstrings
+      - name: Specify docstring to use while building the wheel
+        run: echo "DEPTHAI_PYTHON_DOCSTRINGS_INPUT=$PWD/docstrings/depthai_python_docstring.hpp" >> $GITHUB_ENV
+
       - name: Append build hash if not a tagged commit
         if: startsWith(github.ref, 'refs/tags/v') != true
         run: echo "BUILD_COMMIT_HASH=${{github.sha}}" >> $GITHUB_ENV

diff --git a/docs/.readthedocs.yml → .readthedocs.yml b/docs/.readthedocs.yml → .readthedocs.yml
@@ -5,10 +5,19 @@
 # Required
 version: 2
 
+build:
+  image: latest
+
+# Submodules
+submodules:
+  include:
+    - depthai-core
+  recursive: true
+
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   builder: dirhtml
-  configuration: source/conf.py
+  configuration: docs/readthedocs/conf.py
 
 # Build documentation with MkDocs
 #mkdocs:
@@ -22,4 +31,4 @@ formats:
 python:
   version: 3.8
   install:
-    - requirements: requirements.txt
+    - requirements: docs/readthedocs/requirements.txt
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -3,8 +3,11 @@ cmake_minimum_required(VERSION 3.4) # For Hunter
 # Set defaults
 # PIC toolchain as we are building a shared library
 set(CMAKE_TOOLCHAIN_FILE "${CMAKE_CURRENT_LIST_DIR}/cmake/toolchain/pic.cmake" CACHE STRING "")
-# Build dependencies as 'Release' only by default
-set(HUNTER_CONFIGURATION_TYPES "Release" CACHE STRING "Hunter dependencies list of build configurations")
+
+# Build dependencies as 'Release' only by default (if not MSVC, as it requires same debug level for libraries to be linked against)
+if(NOT WIN32)
+    set(HUNTER_CONFIGURATION_TYPES "Release" CACHE STRING "Hunter dependencies list of build configurations")
+endif()
 
 # Generate combined Hunter config
 file(READ depthai-core/cmake/Hunter/config.cmake depthai_core_hunter_config)
@@ -28,9 +31,25 @@ endif()
 set(TARGET_NAME depthai)
 project(depthai VERSION "1") # revision of bindings [depthai-core].[rev]
 
+# Add module paths
+list(APPEND CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/cmake/")
+list(APPEND CMAKE_MODULE_PATH "${PROJECT_SOURCE_DIR}/depthai-core/cmake")
+
+# Constants
+set(DOCSTRINGS_INCLUDE_PLACEHOLDER_DIR ${CMAKE_CURRENT_BINARY_DIR}/generated/include)
+set(DOCSTRINGS_INCLUDE_PLACEHOLDER_PATH ${DOCSTRINGS_INCLUDE_PLACEHOLDER_DIR}/docstring.hpp)
+set(DOCSTRINGS_OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/generated/include/depthai_python_docstring.hpp)
+
 # First specify options
 option(DEPTHAI_PYTHON_ENABLE_TESTS "Enable tests" OFF)
-option(DEPTHAI_PYTHON_TEST_EXAMPLES "Test examples - examples will be ran as a part of the test suite" OFF)
+option(DEPTHAI_PYTHON_ENABLE_EXAMPLES "Enable examples" OFF)
+option(DEPTHAI_PYTHON_BUILD_DOCS "Build documentation - see docs/requirements.txt for needed dependencies" OFF)
+option(DEPTHAI_PYTHON_BUILD_DOCSTRINGS "Generate docstrings from header files if module 'pybind11_mkdoc' available" ON)
+set(DEPTHAI_PYTHON_DOCSTRINGS_INPUT ${DOCSTRINGS_OUTPUT} CACHE FILEPATH "Path to docstring for bindings") 
+set(DEPTHAI_PYTHON_DOCSTRINGS_OUTPUT ${DOCSTRINGS_OUTPUT} CACHE FILEPATH "Path where docstring file will be generated") 
+if(DEPTHAI_PYTHON_BUILD_DOCSTRINGS)
+    option(DEPTHAI_PYTHON_FORCE_DOCSTRINGS "Force that docstrings are generated, module 'pybind11_mkdoc' required" OFF)
+endif()
 
 # Add external dependencies
 add_subdirectory(external)
@@ -64,8 +83,24 @@ pybind11_add_module(${TARGET_NAME}
     src/log/LogBindings.cpp
 )
 
-# Add include directory (src)
-target_include_directories(${TARGET_NAME} PRIVATE src)
+# Configure include placeholder with INPUT path
+configure_file(cmake/docstring.hpp.in ${DOCSTRINGS_INCLUDE_PLACEHOLDER_PATH})
+# Add target to generate docstrings
+if (DEPTHAI_PYTHON_BUILD_DOCSTRINGS)
+    include(pybind11-mkdoc)
+    # Check if pybind11_mkdoc available and create target
+    target_pybind11_mkdoc_setup(${DEPTHAI_PYTHON_DOCSTRINGS_OUTPUT} depthai-core ${DEPTHAI_PYTHON_FORCE_DOCSTRINGS})
+    if(NOT TARGET pybind11_mkdoc)
+        # Generate default docstrings to OUTPUT path
+        configure_file(cmake/default_docstring.hpp.in ${DEPTHAI_PYTHON_DOCSTRINGS_OUTPUT} COPYONLY)
+    endif()
+else()
+    # Generate default docstrings to OUTPUT path
+    configure_file(cmake/default_docstring.hpp.in ${DEPTHAI_PYTHON_DOCSTRINGS_OUTPUT} COPYONLY)
+endif()
+
+# Add include directory
+target_include_directories(${TARGET_NAME} PRIVATE src ${DOCSTRINGS_INCLUDE_PLACEHOLDER_DIR})
 
 # Link with libraries
 target_link_libraries(${TARGET_NAME} 
@@ -76,33 +111,55 @@ target_link_libraries(${TARGET_NAME}
         hedley
 )
 
-# Add bindings revision
-target_compile_definitions(${TARGET_NAME} PRIVATE DEPTHAI_PYTHON_BINDINGS_REVISION="${PROJECT_VERSION}")
+# Version consists of: (depthai-core).(bindings revision)[+bindings hash]
+set(DEPTHAI_PYTHON_VERSION "${DEPTHAI_VERSION}.${PROJECT_VERSION}")
 
-# Add default commit hash (dev) if not build by CI
+# Add default commit hash ('dev') if not build by CI
 if(NOT DEFINED ENV{CI} AND NOT DEPTHAI_PYTHON_COMMIT_HASH)   
     set(DEPTHAI_PYTHON_COMMIT_HASH dev)
 endif()
 
-# Add compile definition for bindings
+# Append build info to version
 if(DEPTHAI_PYTHON_COMMIT_HASH)
-    target_compile_definitions(${TARGET_NAME} PRIVATE DEPTHAI_PYTHON_COMMIT_HASH="${DEPTHAI_PYTHON_COMMIT_HASH}")
+    set(DEPTHAI_PYTHON_VERSION "${DEPTHAI_PYTHON_VERSION}+${DEPTHAI_PYTHON_COMMIT_HASH}")    
 endif()
 
+# Add version definition
+target_compile_definitions(${TARGET_NAME} PRIVATE DEPTHAI_PYTHON_VERSION="${DEPTHAI_PYTHON_VERSION}")
+target_compile_definitions(${TARGET_NAME} PRIVATE DEPTHAI_PYTHON_BINDINGS_REVISION="${PROJECT_VERSION}")
+target_compile_definitions(${TARGET_NAME} PRIVATE DEPTHAI_VERSION="${DEPTHAI_VERSION}")
+target_compile_definitions(${TARGET_NAME} PRIVATE DEPTHAI_PYTHON_COMMIT_HASH="${DEPTHAI_PYTHON_COMMIT_HASH}")
+
 # Set compiler features (c++14), and disables extensions
 set_property(TARGET ${TARGET_NAME} PROPERTY CXX_STANDARD 14)
 set_property(TARGET ${TARGET_NAME} PROPERTY CXX_STANDARD_REQUIRED ON)
 set_property(TARGET ${TARGET_NAME} PROPERTY CXX_EXTENSIONS OFF)
 
+# ASAN Settings as we are building and using shared library
+if(SANITIZE_ADDRESS OR SANITIZE_MEMORY OR SANITIZE_THREAD OR SANITIZE_UNDEFINED)
+    # Get asan library to preload
+    if (CMAKE_CXX_COMPILER_ID STREQUAL "Clang")
+        execute_process(COMMAND ${CMAKE_CXX_COMPILER} -print-file-name=libclang_rt.asan-${CMAKE_HOST_SYSTEM_PROCESSOR}.so OUTPUT_VARIABLE LIBASAN_PATH OUTPUT_STRIP_TRAILING_WHITESPACE)
+    elseif (CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
+        execute_process(COMMAND ${CMAKE_CXX_COMPILER} -print-file-name=libasan.so OUTPUT_VARIABLE LIBASAN_PATH OUTPUT_STRIP_TRAILING_WHITESPACE)
+    endif()
+    # Set preload env variable
+    if(APPLE)
+        set(ASAN_ENVIRONMENT_VARS "DYLD_INSERT_LIBRARIES=${LIBASAN_PATH}" "ASAN_OPTIONS=leak_check_at_exit=0")
+    elseif(UNIX)
+        set(ASAN_ENVIRONMENT_VARS "LD_PRELOAD=${LIBASAN_PATH}" "ASAN_OPTIONS=leak_check_at_exit=0")
+    endif()
+    message(STATUS "ASAN environment variables: ${ASAN_ENVIRONMENT_VARS}")
+endif()
+
 ########################
 # Testing
 ########################
-if(DEPTHAI_PYTHON_ENABLE_TESTS OR DEPTHAI_PYTHON_TEST_EXAMPLES)
+if(DEPTHAI_PYTHON_ENABLE_TESTS OR DEPTHAI_PYTHON_ENABLE_EXAMPLES)
     include(CTest)
     enable_testing()
 endif()
 
-
 ########################
 # Tests
 ########################
@@ -113,7 +170,13 @@ endif()
 ########################
 # Examples (can also act as tests)
 ########################
-if (DEPTHAI_PYTHON_TEST_EXAMPLES)
+if (DEPTHAI_PYTHON_ENABLE_EXAMPLES)
     add_subdirectory(examples)
 endif()
 
+########################
+# Documentation
+########################
+if(DEPTHAI_PYTHON_BUILD_DOCS)
+    add_subdirectory(docs)
+endif()
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1,12 +1,16 @@
-include README.md LICENSE
+include README.md LICENSE CMakeLists.txt pyproject.toml
 include find_version.py
+graft cmake
 graft generated
-global-include CMakeLists.txt *.cmake
-recursive-include src *
-recursive-include pybind11/include *.h
+graft ci
 graft external
+graft src
 graft depthai-core
-prune depthai-core/build
+prune depthai-core/build*
+prune depthai-core/tests*
+prune depthai-core/examples*
 prune build
 prune wheelhouse
 prune dist
+prune tests
+prune examples
diff --git a/cmake/default_docstring.hpp.in b/cmake/default_docstring.hpp.in
@@ -0,0 +1,3 @@
+// Default DOC define, which is nullptr aka no docstring
+// This case covers when docstrings couldn't be generated
+#define DOC(...) ((const char*) nullptr)
diff --git a/cmake/docstring.hpp.in b/cmake/docstring.hpp.in
@@ -0,0 +1 @@
+#include "@DEPTHAI_PYTHON_DOCSTRINGS_INPUT@"