docs: organize contents into sections (#3528)

Better organize the content into structures. 

Part 2/N of #2423

Author: eddyxu

docs/arrays.rst

@@ -14,7 +14,7 @@ a 32-bit float: ~1e-38 to ~1e38. By comparison, a 16-bit float has a range of
 ~5.96e-8 to 65504.
 
 Lance provides an Arrow extension array (:class:`lance.arrow.BFloat16Array`)
-and a Pandas extension array (:class:`lance.pandas.BFloat16Dtype`) for BFloat16.
+and a Pandas extension array (:class:`~lance._arrow.PandasBFloat16Type`) for BFloat16.
 These are compatible with the `ml_dtypes <https://github.com/jax-ml/ml_dtypes>`_
 bfloat16 NumPy extension array.
 
@@ -31,7 +31,7 @@ the array:
     2      3.40625
     dtype: lance.bfloat16
 
-To create an an arrow array, use the :func:`lance.arrow.bfloat16_array` function:
+To create an Arrow array, use the :func:`lance.arrow.bfloat16_array` function:
 
 .. code-block:: python
 

docs/blob.rst

@@ -10,11 +10,6 @@ Lance provides a high-level API to store and retrieve large binary objects (blob
 Lance serves large binary data using :py:class:`lance.BlobFile`, which
 is a file-like object that lazily reads large binary objects.
 
-.. autoclass:: lance.BlobFile
-    :members:
-    :show-inheritance:
-    :noindex:
-
 To fetch blobs from a Lance dataset, you can use :py:meth:`lance.dataset.LanceDataset.take_blobs`.
 
 For example, it's easy to use `BlobFile` to extract frames from a video file without

docs/conf.py

@@ -1,7 +1,6 @@
 # Configuration file for the Sphinx documentation builder.
 
 import shutil
-from datetime import datetime
 
 
 def run_apidoc(_):
@@ -18,7 +17,7 @@ def setup(app):
 # -- Project information -----------------------------------------------------
 
 project = "Lance"
-copyright = f"{datetime.today().year}, Lance Developer"
+copyright = "%Y, Lance Developer"
 author = "Lance Developer"
 
 
@@ -29,7 +28,7 @@ def setup(app):
 # ones.
 extensions = [
     "breathe",
-    "sphinx_copybutton",
+    "sphinx_immaterial",
     "sphinx.ext.autodoc",
     "sphinx.ext.doctest",
     "sphinx.ext.githubpages",
@@ -61,20 +60,42 @@ def setup(app):
 
 # -- Options for HTML output -------------------------------------------------
 
-html_theme = "piccolo_theme"
+html_theme = "sphinx_immaterial"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
 
 html_favicon = "_static/favicon_64x64.png"
-# html_logo = "_static/high-res-icon.png"
+html_logo = "_static/high-res-icon.png"
 html_theme_options = {
-    "source_url": "https://github.com/lancedb/lance",
-    "source_icon": "github",
+    "icon": {
+        "repo": "fontawesome/brands/github",
+        "edit": "material/file-edit-outline",
+    },
+    "site_url": "https://github.com/lancedb/lance",
+    "repo_url": "https://github.com/lancedb/lance",
+    "repo_name": "Lance",
+    "features": [
+        "navigation.expand",
+        # "navigation.tabs",
+        "content.tabs.link",
+        "content.code.copy",
+    ],
+    "social": [
+        {
+            "icon": "fontawesome/brands/github",
+            "link": "https://github.com/jbms/sphinx-immaterial",
+            "name": "Source on github.com",
+        },
+        {
+            "icon": "fontawesome/brands/python",
+            "link": "https://pypi.org/project/pylance/",
+        },
+    ],
 }
-html_css_files = ["custom.css"]
+include_in_toc = False
 
 # -- doctest configuration ---------------------------------------------------
 

docs/index.rst

@@ -39,15 +39,33 @@ Preview releases receive the same level of testing as regular releases.
 
 
 .. toctree::
-   :maxdepth: 1
+   :caption: Introduction
+   :maxdepth: 2
 
    Quickstart <./notebooks/quickstart>
    ./read_and_write
-   Lance Formats <./format>
-   Arrays <./arrays>
+
+.. toctree::
+   :caption: Advanced Usage
+   :maxdepth: 1
+
+   Lance Format Spec <./format>
    Blob API <./blob>
-   Integrations <./integrations/integrations>
    Performance Guide <./performance>
+   Tokenizer <./tokenizer>
+   Extension Arrays <./arrays>
+
+.. toctree::
+   :caption: Integrations
+
+   Huggingface <./integrations/huggingface>
+   Tensorflow <./integrations/tensorflow>
+   PyTorch <./integrations/pytorch>
+   Ray <./integrations/ray>
+
+.. toctree::
+   :maxdepth: 1
+
    API References <./api/api>
    Contributor Guide <./contributing>
    Examples <./examples/examples>

docs/integrations/integrations.rst

@@ -1,6 +1,7 @@
 pyarrow
 sphinx>=8
 sphinx-copybutton
+sphinx-immaterial
 breathe
 cython
 pandas

docs/requirements.txt

@@ -6,34 +6,37 @@ If tokenization is needed, you can download language models by yourself.
 You can specify the location where the language models are stored by setting the environment variable LANCE_LANGUAGE_MODEL_HOME.
 If it's not set, the default value is
 
-... code-block::bash
+.. code-block:: bash
+
     ${system data directory}/lance/language_models
 
 It also supports configuring user dictionaries,
 which makes it convenient for users to expand their own dictionaries without retraining the language models.
 
 Language Models of Jieba
----------------
+------------------------
 
 Downloading the Model
-~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
 
-... code-block::bash
     python -m lance.download jieba
 
 The language model is stored by default in `${LANCE_LANGUAGE_MODEL_HOME}/jieba/default`.
 
 Using the Model
-~~~~~~~~~~~
+~~~~~~~~~~~~~~~
 
-... code-block::python
+.. code-block:: python
     ds.create_scalar_index("text", "INVERTED", base_tokenizer="jieba/default")
 
 User Dictionaries
-~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~
 Create a file named config.json in the root directory of the current model.
 
-... code-block::json
+.. code-block:: json
+
     {
         "main": "dict.txt",
         "users": ["path/to/user/dict.txt"]
@@ -44,30 +47,32 @@ Create a file named config.json in the root directory of the current model.
 
 
 Language Models of Lindera
----------------
+--------------------------
 
 Downloading the Model
-~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
 
-... code-block::bash
     python -m lance.download lindera -l [ipadic|ko-dic|unidic]
 
 Note that the language models of Lindera need to be compiled. Please install lindera-cli first. For detailed steps, please refer to https://github.com/lindera/lindera/tree/main/lindera-cli.
 
 The language model is stored by default in ${LANCE_LANGUAGE_MODEL_HOME}/lindera/[ipadic|ko-dic|unidic]
 
 Using the Model
-~~~~~~~~~~~
+~~~~~~~~~~~~~~~
+
+.. code-block:: python
 
-... code-block::python
     ds.create_scalar_index("text", "INVERTED", base_tokenizer="lindera/ipadic")
 
 User Dictionaries
-~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~
 
 Create a file named config.json in the root directory of the current model.
 
-... code-block::json
+.. code-block::json
     {
         "main": "main",
         "users": "path/to/user/dict.bin",
@@ -80,7 +85,7 @@ Create a file named config.json in the root directory of the current model.
 
 
 Create your own language model
----------------
+------------------------------
 
 Put your language model into `LANCE_LANGUAGE_MODEL_HOME`.
 

docs/tokenizer.rst

@@ -1,5 +1,13 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "7980c1ca",
+   "metadata": {},
+   "source": [
+    "# Quickstart"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 1,
@@ -981,7 +989,7 @@
     }
    ],
    "source": [
-    "%%time \n",
+    "%%time\n",
     "\n",
     "sift1m.create_index(\n",
     "    \"vector\",\n",