DF Documentation 🔖

.github/workflows/doc-build.yml

@@ -0,0 +1,148 @@
+name: doc-build
+
+on: [push, pull_request, workflow_dispatch]
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  build-source:
+    runs-on: windows-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup conda environment
+        uses: conda-incubator/setup-miniconda@v2
+        with:
+          auto-update-conda: true
+          python-version: 3.9.1
+
+      - name: Create diff_check conda environment
+        run: |
+          conda env create -f environment.yml
+
+      - name: Cache conda environment cache
+        uses: actions/cache@v2
+        with:
+          path: C:\Miniconda\envs\diff_check
+          key: ${{ runner.os }}-conda-${{ hashFiles('environment.yml') }}
+
+      - name: Cmake Configure
+        run: |
+          conda run --name diff_check --no-capture-output cmake -S . -B build -A x64 -DBUILD_PYTHON_MODULE=ON -DBUILD_TESTS=OFF -DRUN_TESTS=OFF
+
+      - name: CMake Build
+        run: conda run --name diff_check --no-capture-output cmake --build build --config Release
+
+        # upload artifacts
+      - name: Move dlls and pyd files to single directories
+        run: |
+          mkdir $env:GITHUB_WORKSPACE\artifacts_dlls
+          mkdir $env:GITHUB_WORKSPACE\artifacts_pyds
+          Get-ChildItem -Path $env:GITHUB_WORKSPACE\build\bin\Release -Filter *.dll -Recurse | Move-Item -Destination $env:GITHUB_WORKSPACE\artifacts_dlls
+          Get-ChildItem -Path $env:GITHUB_WORKSPACE\build\Release -Filter *.pyd -Recurse | Move-Item -Destination $env:GITHUB_WORKSPACE\artifacts_pyds
+        shell: pwsh
+      - name: Upload artifacts - dlls
+        uses: actions/upload-artifact@v2
+        with:
+          name: __build_artifacts_dlls__
+          path: ${{ github.workspace }}/artifacts_dlls/*
+      - name: Upload artifacts - pyds
+        uses: actions/upload-artifact@v2
+        with:
+          name: __build_artifacts_pyds__
+          path: ${{ github.workspace }}/artifacts_pyds/*
+
+
+  build-docs:
+    runs-on: windows-latest
+    needs: build-source
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup conda environment
+        uses: conda-incubator/setup-miniconda@v2
+        with:
+          auto-update-conda: true
+          python-version: 3.9.1
+
+      - name: Restore conda environment cache
+        uses: actions/cache@v2
+        with:
+          path: C:\Miniconda\envs\diff_check
+          key: ${{ runner.os }}-conda-${{ hashFiles('environment.yml') }}
+          restore-keys: |
+            ${{ runner.os }}-conda-
+
+        # download artifacts
+      - name: Download dlls for doc folder
+        uses: actions/download-artifact@v2
+        with:
+          name: __build_artifacts_dlls__
+          path: ${{github.workspace}}/doc
+      - name: Download pyds for doc folder
+        uses: actions/download-artifact@v2
+        with:
+          name: __build_artifacts_pyds__
+          path: ${{github.workspace}}/doc
+      - name: Download dlls for diffCheck py package
+        uses: actions/download-artifact@v2
+        with:
+          name: __build_artifacts_dlls__
+          path: ${{github.workspace}}/src/gh/diffCheck/diffCheck/dlls
+      - name: Download pyds for diffCheck py package
+        uses: actions/download-artifact@v2
+        with:
+          name: __build_artifacts_pyds__
+          path: ${{github.workspace}}/src/gh/diffCheck/diffCheck
+
+      - name: Sphinx build
+        run: |
+          conda run --name diff_check --no-capture-output sphinx-build -b html -v doc _build
+
+      - name: Upload documentation
+        uses: actions/upload-artifact@v2
+        with:
+          name: __build_sphx_docs__
+          path: ${{ github.workspace }}/_build
+
+
+  page-deployement:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build-docs
+    # Run only on pushes to the default branch
+    if: github.ref == 'refs/heads/main'
+    # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+    # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+    concurrency:
+      group: "pages"
+      cancel-in-progress: false
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Download sphinx docs
+        uses: actions/download-artifact@v2
+        with:
+          name: __build_sphx_docs__
+          path: ${{github.workspace}}/_build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: '_build'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/py-sanity-check.yml

@@ -0,0 +1,38 @@
+name: py-sanity-checks
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: windows-latest
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Setup conda environment
+      uses: conda-incubator/setup-miniconda@v2
+      with:
+        auto-update-conda: true
+        python-version: 3.9.1
+    - name: Cache conda environment cache
+      uses: actions/cache@v2
+      with:
+        path: C:\Miniconda\envs\diff_check
+        key: ${{ runner.os }}-conda-${{ hashFiles('environment.yml') }}
+        restore-keys: |
+          ${{ runner.os }}-conda-
+      id: cache-conda
+    - name: Create diff_check conda environment if not cached
+      if: steps.cache-conda.outputs.cache-hit != 'true'
+      run: |
+          conda env create -f environment.yml
+
+    - name: Cache pre-commit hooks
+      uses: actions/cache@v2
+      with:
+        path: ~/.cache/pre-commit
+        key: ${{ runner.os }}-precommit-${{ hashFiles('.pre-commit-config.yaml') }}
+    - name: Install pre-commit
+      run: pip install pre-commit
+    - name: Run pre-commit
+      run: conda run --name diff_check --no-capture-output pre-commit run --all-files

.gitignore

@@ -247,3 +247,9 @@ cython_debug/
 
 # egg-info
 *.egg-info/
+
+#######################################
+## Sphinx
+#######################################
+# get rid of output folder
+_build/

.gitmodules

@@ -2,9 +2,6 @@
 	path = deps/googletest
 	url = https://github.com/google/googletest
 	branch = main
-[submodule "deps/eigen"]
-	path = deps/eigen
-	url = https://gitlab.com/libeigen/eigen.git
 [submodule "deps/open3d"]
 	path = deps/open3d
 	url = https://github.com/diffCheckOrg/submodule-open3d.git
@@ -20,3 +17,6 @@
 [submodule "deps/submodule-cilantro"]
 	path = deps/submodule-cilantro
 	url = https://github.com/diffCheckOrg/submodule-cilantro.git
+[submodule "deps/eigen"]
+	path = deps/eigen
+	url = https://gitlab.com/libeigen/eigen.git

.pre-commit-config.yaml

@@ -0,0 +1,44 @@
+# Install the pre-commit hooks below with
+# 'pre-commit install'
+
+# Auto-update the version of the hooks with
+# 'pre-commit autoupdate'
+
+# Run the hooks on all files with
+# 'pre-commit run --all'
+
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v4.6.0
+  hooks:
+  - id: check-ast
+    exclude: ^deps/
+  - id: check-merge-conflict
+  - id: end-of-file-fixer
+    # only include python files
+    files: \.py$
+  - id: trailing-whitespace
+    # only include python files
+    files: \.py$
+  - id: end-of-file-fixer
+    # only include python files
+    files: \.py$
+
+- repo: https://github.com/pre-commit/mirrors-mypy
+  rev: 'v1.11.0'
+  hooks:
+  - id: mypy
+    files: (src/gh|tests|invokes\.py)
+    exclude: src/gh/components/
+    additional_dependencies: [
+      types-requests==2.31.0,
+      numpy==2.0.1,
+      pytest==8.3.1,
+      types-setuptools>=71.1.0.20240818
+      ]
+    args: [--config=pyproject.toml]
+
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.4.4
+  hooks:
+  - id: ruff

CMakeLists.txt

@@ -137,6 +137,7 @@ if (BUILD_PYTHON_MODULE)
     set(PYBINDMODULE_NAME diffcheck_bindings)
     set(PYPI_DIR ${CMAKE_CURRENT_SOURCE_DIR}/src/gh/diffCheck/diffCheck)
     set(TARGET_DLL_PYPI_DIR ${CMAKE_CURRENT_SOURCE_DIR}/src/gh/diffCheck/diffCheck/dlls)
+    set(SPHINX_DOC_DIR ${CMAKE_CURRENT_SOURCE_DIR}/doc)
 
     download_submodule_project(pybind11)
     add_subdirectory(deps/pybind11)
@@ -162,12 +163,18 @@ if (BUILD_PYTHON_MODULE)
         ${PYPI_DIR}
         )
     copy_dlls(${TARGET_DLL_PYPI_DIR} ${PYBINDMODULE_NAME})
+    # copy the pyd/dlls for the sphinx documentation
+    add_custom_command(TARGET ${PYBINDMODULE_NAME} POST_BUILD
+        COMMAND ${CMAKE_COMMAND} -E copy
+        $<TARGET_FILE:${PYBINDMODULE_NAME}>
+        ${SPHINX_DOC_DIR}
+        )
+    copy_dlls(${SPHINX_DOC_DIR} ${PYBINDMODULE_NAME})
 endif()
 
 #--------------------------------------------------------------------------
 # Tests
 #--------------------------------------------------------------------------
 if(BUILD_TESTS)
     include(tests)
-endif()
-
+endif()