Add Python bindings

.codedocs

@@ -1 +1 @@
-DOXYFILE=.doxygen.txt
+DOXYFILE=docs/Doxyfile

.github/workflows/ci.yml

@@ -172,6 +172,40 @@ jobs:
         working-directory: ${{runner.workspace}}/build
         run: make test
 
+  pybind11:
+    needs: [build-ubuntu, build-mac]
+    strategy:
+      fail-fast: false
+      matrix:
+        platform: [macos-latest, ubuntu-latest] #windows-latest,
+        # python-version: [3.5, 3.6, 3.7, 3.8]
+        python-version: [3.6]
+    runs-on: ${{ matrix.platform }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Setup apt
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt update
+          sudo apt install -y libeigen3-dev
+      - name: Setup brew
+        if: runner.os == 'macOS'
+        run: brew install eigen
+      - name: Setup
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest "pybind11[global]"
+          pip install -r requirements.txt
+      - name: Build
+        run: pip install .
+      - name: Test
+        run: pytest
+
   # arm64:
   #   needs: [build-ubuntu]
   #   runs-on: ubuntu-latest

.github/workflows/docs.yml

@@ -0,0 +1,91 @@
+name: documentation
+on:
+  push:
+    branches: devel
+  workflow_dispatch:
+
+jobs:
+
+  # There is no way as of now to move artifacts around jobs and
+  # across workflows. So we build the Python bindings here too.
+  build:
+    runs-on: ubuntu-20.04
+    steps:
+
+      # Build manifpy
+
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.6
+      - name: Setup apt
+        run: |
+          sudo apt update
+          sudo apt install -y libeigen3-dev
+      - name: Setup
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest "pybind11[global]"
+          pip install -r requirements.txt
+      - name: Build
+        run: pip install .
+
+  # build:
+  #   runs-on: ubuntu-20.04
+  #   needs: [pybind11]
+  #   steps:
+  #     - name: Checkout
+  #       uses: actions/checkout@v2
+  #     - name: Set up Python
+  #       uses: actions/setup-python@v2
+
+      # Build documentation website
+
+      - name: Fetch apt deps
+        run: |
+          sudo apt update
+          sudo apt install -y libeigen3-dev flex bison doxygen graphicsmagick-imagemagick-compat
+      - name: Fetch Python deps
+        run: python -m pip install jinja2 Pygments
+      - name: Fetch m.css
+        working-directory: ${{runner.workspace}}/manif/docs
+        run: git clone git://github.com/mosra/m.css
+
+      - name: Build Python docs
+        working-directory: ${{runner.workspace}}/manif/docs
+        run: python m.css/documentation/python.py conf_python.py
+      - name: Build C++ docs
+        working-directory: ${{runner.workspace}}/manif/docs
+        run: |
+          mkdir -p site/cpp
+          python m.css/documentation/doxygen.py conf_cpp.py
+      - name: Build site
+        working-directory: ${{runner.workspace}}/manif/docs
+        run: python m.css/documentation/doxygen.py conf.py
+
+      - name: Latex equation white color
+        working-directory: ${{runner.workspace}}/manif/docs
+        run: ./fix_latex_color.sh
+
+      - name: Archive artifacts
+        uses: actions/upload-artifact@v2
+        with:
+          name: site
+          path: docs/site
+
+  deploy:
+    runs-on: ubuntu-20.04
+    needs: [build]
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v2
+        with:
+          name: site
+      - name: Deploy
+        uses: JamesIves/[email protected]
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BRANCH: gh-pages
+          FOLDER: site

.gitignore

@@ -4,5 +4,14 @@
 .settings
 .tags
 build
-doc
-doxygen_warnings.txt
+docs/xml
+docs/html
+docs/site
+docs/m.css
+*doxygen_warnings.txt
+*.cache
+.vscode
+*.egg-info
+*.so
+*__pycache__
+.pytest_cache

CMakeLists.txt

@@ -54,6 +54,13 @@ endif()
 option(BUILD_TESTING "Build all tests." OFF)
 option(ENABLE_CPPCHECK "Enable cppcheck." OFF)
 option(BUILD_EXAMPLES "Build all examples." OFF)
+option(BUILD_PYTHON_BINDINGS "Build Python bindings with pybind11." OFF)
+option(BUILD_TESTING_PYTHON "Build Python tests only." OFF)
+
+if (BUILD_PYTHON_BINDINGS)
+  find_package(pybind11 REQUIRED)
+  add_subdirectory(python)
+endif()
 
 ###########
 ## Build ##
@@ -263,3 +270,10 @@ if(BUILD_TESTING)
   add_subdirectory(test)
 
 endif(BUILD_TESTING)
+
+if(BUILD_PYTHON_BINDINGS AND (BUILD_TESTING OR BUILD_TESTING_PYTHON))
+
+  enable_testing()
+  add_subdirectory(test/python)
+
+endif()

CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing
+
+## General guidelines
+
+**manif** is developed according to Vincent Driessen's [Gitflow Workflow][git-workflow].
+This means,
+
+- the `master` branch is for releases only.
+- development is done on feature branches.
+- finished features are integrated via PullRequests into the branch `devel`.
+
+For a PullRequest to get merged into `devel`, it must pass
+
+- Review by one of the maintainers.
+  - Are the changes introduced in scope of **manif**?
+  - Is the documentation updated?
+  - Are enough reasonable tests added?
+  - Will these changes break the API?
+  - Do the new changes follow the current style of naming?
+- Compile / Test / Run on all target environments.
+
+Note: The test suite detailed below is run in CI for many targets environments including,
+
+- Ubuntu 16.04/18.04/20.04
+- MacOS 10.15
+- Visual Studio 15
+
+## Development environment
+
+We will detail here how to set up a development environment.
+It is recommended to use containers if you do not want to install the dependencies on your host.
+You may refer to [this blog post](lxd-post) to set up a LXD container.
+
+First let us clone the **manif** repo,
+
+```terminal
+git clone https://github.com/artivis/manif.git
+cd manif
+```
+
+Let's install all dependencies for development and testing,
+
+```terminal
+apt install libeigen3-dev
+python3 -m pip install "pybind11[global]" pytest
+python3 -m pip install -r requirements
+```
+
+We can now build **manif**, its Python wrappers and all tests,
+
+```terminal
+mkdir build && cd build
+cmake -DBUILD_TESTING=ON -DBUILD_EXAMPLES=ON -DBUILD_PYTHON_BINDINGS=ON -DBUILD_EXAMPLES=ON ..
+make
+```
+
+To run the C++ tests execute the following,
+
+```terminal
+ctest --output-on-failure
+```
+
+To run the Python tests,
+
+```terminal
+cd manif
+pytest
+```
+
+[//]: # (URLs)
+
+[git-workflow]: http://nvie.com/posts/a-successful-git-branching-model
+[lxd-post]: https://artivis.github.io/post/2020/lxc