ARROW-184 API Docs are not rendered in Latest Docs (#172)

* ARROW-184 API Docs are not rendered in Latest Docs

* fix config

* update config

* update config

* update config

* use gxx

* include pyarrow in conda env

* fix config

* fix config

* make c extensions optional for docs

* use a default libbson version

* fix html handling

* more docs fixes

* more docs fixes

* more docs fixes

* more docs fixes

* more docs fixes

* more docs fixes

* more docs fixes

* try again

* update comment

* undo changes

* undo change

* undo change

Author: blink1073

.github/workflows/test-python.yml

@@ -43,7 +43,7 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
           cache: 'pip'
-          cache-dependency-path: '**/setup.cfg'
+          cache-dependency-path: '**/pyproject.toml'
       - name: Set up env
         run: |
            echo "LIBBSON_INSTALL_DIR=$PWD/libbson" >> $GITHUB_ENV
@@ -98,26 +98,16 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Cache conda
-        uses: actions/cache@v3
-        env:
-          # Increase this value to reset cache if environment.yml has not changed
-          CACHE_NUMBER: 0
-        with:
-          path: ~/conda_pkgs_dir
-          key:
-            ${{ runner.os }}-conda-${{ env.CACHE_NUMBER }}-${{
-            hashFiles('bindings/python/docs/environment.yml') }}
-      - uses: conda-incubator/setup-miniconda@v2
+      - name: Setup Python
+        uses: actions/setup-python@v4
         with:
-          auto-update-conda: true
-          activate-environment: mongo_arrow_documentation
-          environment-file: bindings/python/docs/environment.yml
-          use-only-tar-bz2: true  # IMPORTANT: This needs to be set for caching to work properly!
+          python-version: 3.9
+          cache: 'pip'
+          cache-dependency-path: '**/pyproject.toml'
       - name: Install lib
         shell: bash -l {0}
         run: |
-          pip install .
+          NO_EXT=1 pip install .[docs]
       - name: Build docs with warnings
         shell: bash -l {0}
         run: |

.readthedocs.yaml

@@ -1,10 +1,10 @@
 version: 2
-sphinx:
-  configuration: ./bindings/python/docs/source/conf.py
-conda:
-  environment: ./bindings/python/docs/environment.yml
-python:
-  install:
-    # install the package itself
-    - method: pip
-      path: ./bindings/python
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.9"
+  commands:
+    - NO_EXT=1 pip install ./bindings/python[docs]
+    - mkdir --parents $READTHEDOCS_OUTPUT/html/
+    - cd ./bindings/python/docs && make html
+    - cp --recursive ./bindings/python/docs/build/html/* $READTHEDOCS_OUTPUT/html/

bindings/python/docs/environment.yml

@@ -26,11 +26,21 @@
 from pymongo.common import MAX_WRITE_BATCH_SIZE
 from pymongoarrow.context import PyMongoArrowContext
 from pymongoarrow.errors import ArrowWriteError
-from pymongoarrow.lib import process_bson_stream
 from pymongoarrow.result import ArrowWriteResult
 from pymongoarrow.schema import Schema
 from pymongoarrow.types import _validate_schema, get_numpy_type
 
+try:
+    from pymongoarrow.lib import process_bson_stream
+except ImportError:
+    import traceback
+
+    warnings.warn(
+        "Could not find compiled pymongoarrow.lib extension, please install "
+        "from source or report the following traceback on the issue tracker:\n"
+        f"{traceback.format_exc()}"
+    )
+
 __all__ = [
     "aggregate_arrow_all",
     "find_arrow_all",

bindings/python/pymongoarrow/api.py

@@ -13,36 +13,47 @@
 # limitations under the License.
 from bson.codec_options import DEFAULT_CODEC_OPTIONS
 from pyarrow import Table, timestamp
-from pymongoarrow.lib import (
-    BinaryBuilder,
-    BoolBuilder,
-    CodeBuilder,
-    DatetimeBuilder,
-    Decimal128Builder,
-    DocumentBuilder,
-    DoubleBuilder,
-    Int32Builder,
-    Int64Builder,
-    ListBuilder,
-    ObjectIdBuilder,
-    StringBuilder,
-)
 from pymongoarrow.types import _BsonArrowTypes, _get_internal_typemap
 
-_TYPE_TO_BUILDER_CLS = {
-    _BsonArrowTypes.int32: Int32Builder,
-    _BsonArrowTypes.int64: Int64Builder,
-    _BsonArrowTypes.double: DoubleBuilder,
-    _BsonArrowTypes.datetime: DatetimeBuilder,
-    _BsonArrowTypes.objectid: ObjectIdBuilder,
-    _BsonArrowTypes.decimal128: Decimal128Builder,
-    _BsonArrowTypes.string: StringBuilder,
-    _BsonArrowTypes.bool: BoolBuilder,
-    _BsonArrowTypes.document: DocumentBuilder,
-    _BsonArrowTypes.array: ListBuilder,
-    _BsonArrowTypes.binary: BinaryBuilder,
-    _BsonArrowTypes.code: CodeBuilder,
-}
+try:
+    from pymongoarrow.lib import (
+        BinaryBuilder,
+        BoolBuilder,
+        CodeBuilder,
+        DatetimeBuilder,
+        Decimal128Builder,
+        DocumentBuilder,
+        DoubleBuilder,
+        Int32Builder,
+        Int64Builder,
+        ListBuilder,
+        ObjectIdBuilder,
+        StringBuilder,
+    )
+
+    _TYPE_TO_BUILDER_CLS = {
+        _BsonArrowTypes.int32: Int32Builder,
+        _BsonArrowTypes.int64: Int64Builder,
+        _BsonArrowTypes.double: DoubleBuilder,
+        _BsonArrowTypes.datetime: DatetimeBuilder,
+        _BsonArrowTypes.objectid: ObjectIdBuilder,
+        _BsonArrowTypes.decimal128: Decimal128Builder,
+        _BsonArrowTypes.string: StringBuilder,
+        _BsonArrowTypes.bool: BoolBuilder,
+        _BsonArrowTypes.document: DocumentBuilder,
+        _BsonArrowTypes.array: ListBuilder,
+        _BsonArrowTypes.binary: BinaryBuilder,
+        _BsonArrowTypes.code: CodeBuilder,
+    }
+except ImportError:
+    import traceback
+    import warnings
+
+    warnings.warn(
+        "Could not find compiled pymongoarrow.lib extension, please install "
+        "from source or report the following traceback on the issue tracker:\n"
+        f"{traceback.format_exc()}"
+    )
 
 
 class PyMongoArrowContext:

bindings/python/pymongoarrow/context.py

@@ -47,6 +47,7 @@ content-type = "text/x-rst"
 Homepage = "https://github.com/mongodb-labs/mongo-arrow/tree/main/bindings/python"
 
 [project.optional-dependencies]
+docs = ["sphinx"]
 test = ["pytz", "pytest"]
 
 [tool.setuptools]

bindings/python/pyproject.toml

@@ -172,4 +172,9 @@ def get_extension_modules():
     return modules
 
 
-setup(ext_modules=get_extension_modules())
+if os.environ.get("NO_EXT"):
+    ext_modules = []
+else:
+    ext_modules = get_extension_modules()
+
+setup(ext_modules=ext_modules)