[DOCS] Fit and finish fixes (#110)

Co-authored-by: Jia Yu <[email protected]>

Author: kadolor

README.md

@@ -27,7 +27,11 @@ SedonaDB only runs on a single machine, so it’s perfect for processing smaller
 
 ## Install
 
-You can install Python SedonaDB with `pip install apache-sedona[db]`.
+You can install Python SedonaDB with PyPI:
+
+```sh
+pip install "apache-sedona[db]"
+```
 
 ## Overture buildings example
 

docs/development.md renamed to docs/contributors-guide.md

@@ -17,14 +17,66 @@
   under the License.
 -->
 
-# Development
+# Contributors Guide
+
+This guide details how to set up your development environment as a SedonaDB Contributor.
+
+## Fork and clone the repository
+
+Your first step is to create a personal copy of the repository and connect it to the main project.
+
+1. Fork the repository
+
+      * Navigate to the official [Apache SedonaDB GitHub repository](https://github.com/apache/sedona-db).
+      * Click the **Fork** button in the top-right corner. This creates a complete copy of the project in your own GitHub account.
+
+1. Clone your fork
+
+      * Next, clone your newly created fork to your local machine. This command downloads the repository into a new folder named `sedona-db`.
+      * Replace `YourUsername` with your actual GitHub username.
+
+        ```shell
+        git clone https://github.com/YourUsername/sedona-db.git
+        cd sedona-db
+        ```
+
+1. Configure the remotes
+
+      * Your local repository needs to know where the original project is so you can pull in updates. You'll add a remote link, traditionally named **`upstream`**, to the main Apache SedonaDB repository.
+      * Your fork is automatically configured as the **`origin`** remote.
+
+        ```shell
+        # Add the main repository as the "upstream" remote
+        git remote add upstream https://github.com/apache/sedona-db.git
+        ```
+
+1. Verify the configuration
+
+      * Run the following command to verify that you have two remotes configured correctly: `origin` (your fork) and `upstream` (the main repository).
+
+        ```shell
+        git remote -v
+        ```
+
+      * The output should look like this:
+
+        ```shell
+        origin    https://github.com/YourUsername/sedona-db.git (fetch)
+        origin    https://github.com/YourUsername/sedona-db.git (push)
+        upstream  https://github.com/apache/sedona-db.git (fetch)
+        upstream  https://github.com/apache/sedona-db.git (push)
+        ```
 
 ## Rust
 
-SedonaDB is written and Rust and is a standard `cargo` workspace. You can
-install a recent version of the Rust compiler and cargo from
-[rustup.rs](https://rustup.rs/) and run tests using `cargo test`. A local
-development version of the CLI can be run with `cargo run --bin sedona-cli`.
+SedonaDB is written in Rust and is a standard `cargo` workspace.
+
+You can install a recent version of the Rust compiler and cargo from
+[rustup.rs](https://rustup.rs/) and run tests using `cargo test`.
+
+A local development version of the CLI can be run with `cargo run --bin sedona-cli`.
+
+### Test data setup
 
 Some tests require submodules that contain test data or pinned versions of
 external dependencies. These submodules can be initialized with:
@@ -40,16 +92,26 @@ Additionally, some of the data required in the tests can be downloaded by runnin
 python submodules/download-assets.py
 ```
 
+### System dependencies
+
 Some crates wrap external native libraries and require system dependencies
-to build. At this time the only crate that requires this is the sedona-s2geography
-crate, which requires [CMake](https://cmake.org),
-[Abseil](https://github.com/abseil/abseil-cpp) and OpenSSL. These can be installed
-on MacOS with [Homebrew](https://brew.sh):
+to build.
+
+!!!note "`sedona-s2geography`"
+    At this time, the only crate that requires this is the `sedona-s2geography`
+    crate, which requires [CMake](https://cmake.org),
+    [Abseil](https://github.com/abseil/abseil-cpp) and OpenSSL.
+
+#### macOS
+
+These can be installed on macOS with [Homebrew](https://brew.sh):
 
 ```shell
 brew install abseil openssl cmake geos
 ```
 
+#### Linux and Windows
+
 On Linux and Windows, it is recommended to use [vcpkg](https://github.com/microsoft/vcpkg)
 to provide external dependencies. This can be done by setting the `CMAKE_TOOLCHAIN_FILE`
 environment variable:
@@ -58,7 +120,9 @@ environment variable:
 export CMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake
 ```
 
-When using VSCode, it may be necessary to set this environment variable in settings.json
+#### Visual Studio Code (VSCode) Configuration
+
+When using VSCode, it may be necessary to set this environment variable in `settings.json`
 such that it can be found by rust-analyzer when running build/run tasks:
 
 ```json
@@ -75,8 +139,9 @@ such that it can be found by rust-analyzer when running build/run tasks:
 ## Python
 
 Python bindings to SedonaDB are built with the [Maturin](https://www.maturin.rs) build
-backend. Installing a development version of the main Python bindings the first time
-can be done with:
+backend.
+
+To install a development version of the main Python bindings for the first time, run the following commands:
 
 ```shell
 cd python/sedonadb
@@ -92,12 +157,16 @@ maturin develop
 
 ## Debugging
 
+### Rust
+
 Debugging Rust code is most easily done by writing or finding a test that triggers
 the desired behavior and running it using the *Debug* selection in
 [VSCode](https://code.visualstudio.com/) with the
 [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer)
-extension. Rust code can also debugged using the CLI by finding the `main()` function in
-sedona-cli and choosing the *Debug* run option.
+extension. Rust code can also be debugged using the CLI by finding the `main()` function in
+`sedona-cli` and choosing the *Debug* run option.
+
+### Python, C, and C++
 
 Installation of Python bindings with `maturin develop` ensures a debug-friendly build for
 debugging Rust, Python, or C/C++ code. Python code can be debugged using breakpoints in
@@ -114,7 +183,9 @@ In general, there is at least one benchmark for every implementation of a functi
 and a few other benchmarks for low-level iteration where work was done to optimize
 specific cases.
 
-Briefly, benchmarks for a specific crate can be run with `cargo bench`:
+### Running benchmarks
+
+Benchmarks for a specific crate can be run with `cargo bench`:
 
 ```shell
 cd rust/sedona-geo
@@ -129,17 +200,22 @@ to read for a specific crate).
 cargo bench -- st_area
 ```
 
+### Managing results
+
 By default, criterion saves the last run and will report the difference between the
 current benchmark and the last time it was run (although there are options to
-save and load various baselines). A report containing the last run for any
-benchmark that was ever run can be opened with:
+save and load various baselines).
 
-```shell
-# MacOS
-open target/criterion/report/index.html
-# Ubuntu
-xdg-open target/criterion/report/index.html
-```
+A report of the latest results for all benchmarks can be opened with the following command:
+
+=== "macOS"
+    ```shell
+    open target/criterion/report/index.html
+    ```
+=== "Ubuntu"
+    ```shell
+    xdg-open target/criterion/report/index.html
+    ```
 
 All previous saved benchmark runs can be cleared with:
 
@@ -149,6 +225,16 @@ rm -rf target/criterion
 
 ## Documentation
 
-* `mkdocs serve` - Start the live-reloading docs server.
-* `mkdocs build` - Build the documentation site.
-* `mkdocs -h` - Print help message and exit.
+To contribute to the SedonaDB documentation:
+
+1. Clone the repository and create a fork.
+1. Install the Documentation dependencies:
+    ```sh
+    pip install -r docs/requirements.txt
+    ```
+1. Make your changes to the documentation files.
+1. Preview your changes locally using these commands:
+    * `mkdocs serve` - Start the live-reloading docs server.
+    * `mkdocs build` - Build the documentation site.
+    * `mkdocs -h` - Print help message and exit.
+1. Push your changes and open a pull request.

docs/index.md

@@ -1,6 +1,5 @@
 ---
 hide:
-  - navigation
 
 title: Introducing SedonaDB
 ---
@@ -24,30 +23,45 @@ title: Introducing SedonaDB
   under the License.
 -->
 
-SedonaDB is a high-performance, dependency-free geospatial compute engine designed for single-node processing, making it ideal for smaller datasets on local machines or cloud instances.
+SedonaDB is a single-node analytical database engine with geospatial as the first-class citizen.
+
+Fast and dependency-free, SedonaDB is ideal for working with smaller datasets located on local machines or cloud instances.
 
 The initial `0.1` release supports a core set of vector operations, with comprehensive vector and raster computation capabilities planned for the near future.
 
+For distributed workloads, you can still leverage the power of SedonaSpark, SedonaFlink, or SedonaSnow.
+
 ## Key features
 
 SedonaDB has several advantages:
 
 * **Exceptional Performance:** Built in Rust to process massive geospatial datasets with exceptional speed.
 * **Unified Geospatial Toolkit:** Access a comprehensive suite of functions for both vector and raster data in a single, powerful library.
-* **Seamless Ecosystem Integration:** Built on Apache Arrow for smooth interoperability with popular data science libraries like GeoPandas, DuckDB, and Polars.
+* **Extensive Ecosystem Integration:** Built on Apache Arrow for smooth interoperability with popular data science libraries like GeoPandas, DuckDB, and Polars.
 * **Flexible APIs:** Effortlessly switch between Python and SQL interfaces to match your preferred workflow and skill set.
 * **Guaranteed CRS Propagation:** Automatically manages coordinate reference systems (CRS) to ensure spatial accuracy and prevent common errors.
 * **Broad File Format Support:** Work with a wide range of both modern and legacy geospatial file formats like geoparquet.
 * **Highly Extensible:** Easily customize and extend the library's functionality to meet your project's unique requirements.
 
-## Run a query in SQL, Python, or Rust
+## Install SedonaDB
+
+Here's how to install SedonaDB with various build tools:
+
+=== "pip"
+
+	```bash
+	pip install "apache-sedona[db]"
+	```
+
+=== "R"
 
-SedonaDB offers a flexible query interface in SQL, Python, or Rust.
+	```bash
+	install.packages("sedonadb", repos = "https://community.r-multiverse.org")
+	```
 
-Engineered for speed, SedonaDB provides performant geospatial processing on a single machine. This makes it perfect for the rapid analysis of smaller datasets, whether you're working locally or on a cloud server. While the initial release focuses on core vector operations, a full suite of vector and raster computations is on the roadmap.
+## Run a query in SQL, Python, Rust, or R
 
-For massive, distributed workloads, you can leverage the power of SedonaSpark,
-SedonaFlink, or SedonaSnow.
+SedonaDB offers a flexible query interface.
 
 === "SQL"
 
@@ -58,7 +72,7 @@ SedonaFlink, or SedonaSnow.
 === "Python"
 
 	```python
-	import seonda.db
+	import sedona.db
 
 	sd = sedona.db.connect()
 	sd.sql("SELECT ST_Point(0, 1) as geom")
@@ -86,21 +100,6 @@ SedonaFlink, or SedonaSnow.
         sd_sql("SELECT ST_Point(0, 1) as geom")
 	```
 
-## Install SedonaDB
-
-Here's how to install SedonaDB with various build tools:
-
-=== "pip"
-
-	```bash
-	pip install "apache-sedona[db]"
-	```
-
-=== "R"
-
-	```bash
-	install.packages("sedonadb", repos = "https://community.r-multiverse.org")
-	```
 
 ## Have questions?