docs: convert docs to use mkdocs (#1731)

# Description
Completed the outstanding tasks in #1708

Also changed theme from readthedocs to mkdocs - both are built-in but
latter looks sleeker

# Related Issue(s)
closes #1708

---------

Co-authored-by: Robert Pack <[email protected]>
Co-authored-by: R. Tyler Croy <[email protected]>

.gitignore

@@ -27,4 +27,5 @@ Cargo.lock
 !/delta-inspect/Cargo.lock
 !/proofs/Cargo.lock
 
-justfile
+justfile
+site

docs/python_api.md

@@ -1,6 +1,6 @@
 # Python API Reference
 
-## DeltaTable
+## Delta Table
 
 ::: deltalake.table
 
@@ -13,16 +13,28 @@
 Schemas, fields, and data types are provided in the ``deltalake.schema`` submodule.
 
 ::: deltalake.schema.Schema
+    options:
+        show_root_heading: true
 
 ::: deltalake.schema.PrimitiveType
+    options:
+        show_root_heading: true
 
 ::: deltalake.schema.ArrayType
+    options:
+        show_root_heading: true
 
 ::: deltalake.schema.MapType
+    options:
+        show_root_heading: true
 
 ::: deltalake.schema.Field
+    options:
+        show_root_heading: true
 
 ::: deltalake.schema.StructType
+    options:
+        show_root_heading: true
 
 ## Data Catalog
 

docs/usage/examining-table.md

@@ -14,7 +14,7 @@ The delta log maintains basic metadata about a table, including:
     to have data deleted from it.
 
 Get metadata from a table with the
-[DeltaTable.metadata()][] method:
+[DeltaTable.metadata()][deltalake.table.DeltaTable.metadata] method:
 
 ``` python
 >>> from deltalake import DeltaTable
@@ -27,12 +27,12 @@ Metadata(id: 5fba94ed-9794-4965-ba6e-6ee3c0d22af9, name: None, description: None
 
 The schema for the table is also saved in the transaction log. It can
 either be retrieved in the Delta Lake form as
-[deltalake.schema.Schema][] or as a
+[Schema][deltalake.schema.Schema] or as a
 PyArrow schema. The first allows you to introspect any column-level
 metadata stored in the schema, while the latter represents the schema
 the table will be loaded into.
 
-Use [DeltaTable.schema][] to retrieve the delta lake schema:
+Use [DeltaTable.schema][deltalake.table.DeltaTable.schema] to retrieve the delta lake schema:
 
 ``` python
 >>> from deltalake import DeltaTable
@@ -43,14 +43,14 @@ Schema([Field(id, PrimitiveType("long"), nullable=True)])
 
 These schemas have a JSON representation that can be retrieved. To
 reconstruct from json, use
-[deltalake.schema.Schema.from_json()][].
+[DeltaTable.schema.to_json()][deltalake.schema.Schema.to_json].
 
 ``` python
->>> dt.schema().json()
+>>> dt.schema().to_json()
 '{"type":"struct","fields":[{"name":"id","type":"long","nullable":true,"metadata":{}}]}'
 ```
 
-Use [deltalake.schema.Schema.to_pyarrow()][] to retrieve the PyArrow schema:
+Use [DeltaTable.schema.to_pyarrow()][deltalake.schema.Schema.to_pyarrow] to retrieve the PyArrow schema:
 
 ``` python
 >>> dt.schema().to_pyarrow()

docs/usage/index.md

@@ -1,6 +1,6 @@
 # Usage
 
-A [DeltaTable][] represents the state of a
+A [DeltaTable][deltalake.table.DeltaTable] represents the state of a
 delta table at a particular version. This includes which files are
 currently part of the table, the schema of the table, and other metadata
 such as creation time.

mkdocs.yml

@@ -1,6 +1,8 @@
 site_name: Python Delta Lake Documentation
 theme:
-  name: readthedocs
+  name: mkdocs
+  navigation_depth: 2
+  hljs_style: nord
 nav:
   - Home: index.md
   - Installation: installation.md
@@ -14,22 +16,30 @@ nav:
   - API Reference: python_api.md
 
 plugins:
-- autorefs
-- mkdocstrings:
-    handlers:
-      python:
-        path: [../python]
-        rendering:
-          heading_level: 4
-          show_source: false
-          show_symbol_type_in_heading: true
-          show_signature_annotations: true
-          show_root_heading: true
-          members_order: source
-        import:
-          # for cross references
-          - https://arrow.apache.org/docs/objects.inv
-          - https://pandas.pydata.org/docs/objects.inv
+  - autorefs
+  - mkdocstrings:
+      handlers:
+        python:
+          path: [../python]
+          options:
+            # docstring_style: sphinx
+            docstring_section_style: table
+            docstring_section_style: litabst
+            filters: ["!^_", "^__init__$"]
+            heading_level: 3
+            show_source: false
+            show_symbol_type_in_heading: true
+            show_signature_annotations: true
+            show_root_heading: false
+            show_root_full_path: true
+            separate_signature: true
+            docstring_options:
+              ignore_init_summary: false
+            merge_init_into_class: true
+          import:
+            # for cross references
+            - https://arrow.apache.org/docs/objects.inv
+            - https://pandas.pydata.org/docs/objects.inv
 
 markdown_extensions:
   - admonition