Update stubs and docs; Add generate_stub_and_doc.sh

* Use latest pybind11-stubgen with --numpy-array-use-type-var
* Remove previous stubgen.py/stubgen.sh
* Remove generate_pdoc.sh
* Update dev/README.md
* Remove legacy update_bashrc.sh

dev/README.md

@@ -69,17 +69,20 @@ Depending on your python version, you will get a file called `pymp.cpython-310-x
 
 To install the entire package along with python glue code, do `python3.[version] -m pip install .` inside the root directory of the project.
 
-## Documentation Generation
-
-### Stub Generation
-
-Stubs are useful for type checking and IDE autocompletion. To generate stubs, you **first need to have mplib compiled and installed**. Then, do `python3.[version] -m pip install pybind11_stubgen` and then run `bash dev/generate_stubs.sh`. This will generate stubs for the entire project in the `stubs/` directory. Note that you might need to change the version of the python inside the script. The default is 3.11.
-
-### Website Generation
-
-We use `pdoc` to generate the documentation. First install a version of mplib referring to the section above.
-
-Then, you will need to install `pdoc` with `python3.[version] -m pip install pdoc`. The reason the version is important is because `pdoc` will actually do analysis on the files, so it will scrape through the mplib installed in the site package. Then, run `bash dev/generate_pdoc.sh` from the root of MPlib. This will generate the documentation in the `docs/` directory. Note that you might need to change the version of the python inside the script. The default is 3.11.
+## Stubs & Documentation Generation
+
+To generate stubs and documentations, run `./dev/generate_stub_and_doc.sh`.
+By default it uses `python3.10` in docker image [`kolinguo/mplib-build`](https://hub.docker.com/r/kolinguo/mplib-build).
+
+The script does the following:
+* Build a python wheel using [`cibuildwheel`](https://cibuildwheel.readthedocs.io/en/stable/#how-it-works).
+* In a docker container, install the python wheel and
+use [`pybind11-stubgen`](https://github.com/sizmailov/pybind11-stubgen)
+to generate stubs.  
+Copy the generated stubs into [`mplib`](../mplib/).
+* In a docker container, install the python wheel and
+use [`pdoc`](https://pdoc.dev/docs/pdoc.html) to generate documentations.  
+Copy the generated docs into [`docs`](../docs/).
 
 ## GitHub Action CI/CD
 Currently, a GitHub action is setup to build / release / publish python wheels.

dev/generate_stub_and_doc.sh

@@ -0,0 +1,92 @@
+#!/bin/bash
+
+# Python version to build wheels and generate stubs / docs
+PY_VERSION=310
+# Docker image name to install wheel and generate stubs / docs
+IMGNAME="kolinguo/mplib-build:latest"
+
+############################################################
+# Section 0: Bash Error Handling                           #
+############################################################
+set -eEu -o pipefail
+trap 'catch' ERR  # Trap all errors (status != 0) and call catch()
+catch() {
+  local err="$?"
+  local err_command="$BASH_COMMAND"
+  set +xv  # disable trace printing
+
+  echo -e "\n\e[1;31mCaught error in ${BASH_SOURCE[1]}:${BASH_LINENO[0]} ('${err_command}' exited with status ${err})\e[0m" >&2
+  echo "Traceback (most recent call last, command might not be complete):" >&2
+  for ((i = 0; i < ${#FUNCNAME[@]} - 1; i++)); do
+    local funcname="${FUNCNAME[$i]}"
+    [ "$i" -eq "0" ] && funcname=$err_command
+    echo -e "  ($i) ${BASH_SOURCE[$i+1]}:${BASH_LINENO[$i]}\t'${funcname}'" >&2
+  done
+  exit "$err"
+}
+
+############################################################
+# Section 1: Build python wheels                           #
+############################################################
+# Move to the repo folder, so later commands can use relative paths
+SCRIPT_PATH=$(readlink -f "$0")
+REPO_DIR=$(dirname "$(dirname "$SCRIPT_PATH")")
+cd "$REPO_DIR"
+REPO_NAME=$(basename "$REPO_DIR")  # default WORKDIR inside container
+
+echo_info() {
+  echo -e "\n\e[1;36m$1 ...\e[0m"
+}
+
+echo_info "Removing previous wheels under 'wheelhouse/'"
+rm -rfv wheelhouse/*.whl
+
+echo_info "Building wheels with 'dev/build_wheels.sh'"
+dev/build_wheels.sh --py "$PY_VERSION"
+
+############################################################
+# Section 2: Build stubs                                   #
+############################################################
+BUILD_STUB_CMD="\
+  export PATH=\"/opt/python/cp${PY_VERSION}-cp${PY_VERSION}/bin:\${PATH}\" \
+  && python3 -m pip install pybind11-stubgen \
+  && python3 -m pip install wheelhouse/mplib*.whl \
+  && pybind11-stubgen --numpy-array-use-type-var mplib
+"
+# TODO: add ruff
+
+echo_info "Building stubs in docker '${IMGNAME}'"
+docker run -it --rm \
+  -v "$REPO_DIR":/${REPO_NAME} \
+  "$IMGNAME" \
+  bash -c "$BUILD_STUB_CMD"
+
+echo_info "Removing previous stubs under 'mplib/'"
+find mplib -name "*.pyi" -exec rm -v {} \;
+echo_info "Moving generated stubs into 'mplib/'"
+mv -v stubs/mplib/* mplib
+echo_info "Removing 'stubs/'"
+rm -rfv stubs/
+
+############################################################
+# Section 3: Build docs                                    #
+############################################################
+# TODO: switch to other tools to generate docs, README.md should not be included in wheels
+# TODO: do we must install sapien to generate doc?
+BUILD_DOC_CMD="\
+  export PATH=\"/opt/python/cp${PY_VERSION}-cp${PY_VERSION}/bin:\${PATH}\" \
+  && python3 -m pip install pdoc \
+  && python3 -m pip install sapien==3.0.0.dev0 \
+  && python3 -m pip install wheelhouse/mplib*.whl \
+  && cp -v README.md /opt/python/cp${PY_VERSION}-cp${PY_VERSION}/lib/python*/site-packages/mplib \
+  && pdoc -o docs mplib
+"
+
+echo_info "Removing previous docs under 'mplib/docs/'"
+rm -rfv mplib/docs/
+
+echo_info "Building docs in docker '${IMGNAME}'"
+docker run -it --rm \
+  -v "$REPO_DIR":/${REPO_NAME} \
+  "$IMGNAME" \
+  bash -c "$BUILD_DOC_CMD"