This is an automated email from the ASF dual-hosted git repository.
jiayu pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/sedona-db.git
The following commit(s) were added to refs/heads/main by this push:
new 536b450 [DOCS] Changing navigation, fixing typos (#141)
536b450 is described below
commit 536b45069fec021e0c79b33993f02a11cc0c1c91
Author: Kelly-Ann Dolor <[email protected]>
AuthorDate: Tue Sep 23 17:17:58 2025 -0700
[DOCS] Changing navigation, fixing typos (#141)
Co-authored-by: Copilot <[email protected]>
---
CONTRIBUTING.md | 241 ++++++++++++++++++++++++++++++++++++++++++---
docs/contributors-guide.md | 4 +-
docs/crs-examples.ipynb | 6 +-
docs/crs-examples.md | 8 +-
mkdocs.yml | 65 ++++++++----
5 files changed, 282 insertions(+), 42 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 940d7b1..0fda9ad 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -17,28 +17,243 @@
under the License.
-->
-# How to contribute to Apache SedonaDB
+<!---
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
-Welcome! We'd love to have you contribute to Apache SedonaDB!
+ http://www.apache.org/licenses/LICENSE-2.0
-## Did you find a bug?
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
-Create an issue with a reproducible example. Please specify the SedonaDB
version with a code snippet and error message.
+# Contributors Guide
-## Did you create a PR to fix a bug?
+This guide details how to set up your development environment as a SedonaDB
Contributor.
-See
[here](https://sedona.apache.org/latest/community/rule/#make-a-pull-request)
for instructions on how to open PRs.
+## Fork and clone the repository
-We appreciate bug fixes - thank you in advance!
+Your first step is to create a personal copy of the repository and connect it
to the main project.
-## Would you like to add a new feature or change existing code?
+1. Fork the repository
-If you would like to add a feature or change existing behavior, please make
sure to create an issue ticket and get the planned work approved by the core
team first!
+ * Navigate to the official [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.
-It's always better to get aligned with the core devs before writing any code.
+1. Clone your fork
-## Do you have questions about the source code?
+ * 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.
-Feel free to create an issue or join the
[Discord](https://discord.gg/9A3k5dEBsY) with questions!
+ ```shell
+ git clone https://github.com/YourUsername/sedona-db.git
+ cd sedona-db
+ ```
-Thanks for reading and looking forward to collaborating with you!
+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 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 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:
+
+```shell
+git submodule init
+git submodule update --recursive
+```
+
+Additionally, some of the data required in the tests can be downloaded by
running the following script.
+
+```bash
+python submodules/download-assets.py
+```
+
+### System dependencies
+
+Some crates wrap external native libraries and require system dependencies
+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:
+
+```shell
+export CMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake
+```
+
+#### 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
+{
+ "rust-analyzer.runnables.extraEnv": {
+ "CMAKE_TOOLCHAIN_FILE":
"/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake"
+ },
+ "rust-analyzer.cargo.extraEnv": {
+ "CMAKE_TOOLCHAIN_FILE":
"/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake"
+ }
+}
+```
+
+## Python
+
+Python bindings to SedonaDB are built with the
[Maturin](https://www.maturin.rs) build
+backend.
+
+To install a development version of the main Python bindings for the first
time, run the following commands:
+
+```shell
+cd python/sedonadb
+pip install -e ".[test]"
+```
+
+If editing Rust code in either SedonaDB or the Python bindings, you can
recompile the
+native component with:
+
+```shell
+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 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
+any IDE that supports debugging an editable Python package installation (e.g.,
VSCode);
+Rust, C, or C++ code can be debugged using the
+[CodeLLDB](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb)
+*Attach to Process...* command from the command palette in VSCode.
+
+## Low-level benchmarking
+
+Low-level Rust benchmarks use
[criterion](https://github.com/bheisler/criterion.rs).
+In general, there is at least one benchmark for every implementation of a
function
+(some functions have more than one implementation provided by different
libraries),
+and a few other benchmarks for low-level iteration where work was done to
optimize
+specific cases.
+
+### Running benchmarks
+
+Benchmarks for a specific crate can be run with `cargo bench`:
+
+```shell
+cd rust/sedona-geo
+cargo bench
+```
+
+Benchmarks for a specific function can be run with a filter. These can be run
+from the workspace or a specific crate (although the output is usually easier
+to read for a specific crate).
+
+```shell
+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 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:
+
+```shell
+rm -rf target/criterion
+```
+
+## Documentation
+
+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.
diff --git a/docs/contributors-guide.md b/docs/contributors-guide.md
index 2183c65..34589e7 100644
--- a/docs/contributors-guide.md
+++ b/docs/contributors-guide.md
@@ -27,7 +27,7 @@ Your first step is to create a personal copy of the
repository and connect it to
1. Fork the repository
- * Navigate to the official [Apache SedonaDB GitHub
repository](https://github.com/apache/sedona-db).
+ * Navigate to the official [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
@@ -42,7 +42,7 @@ Your first step is to create a personal copy of the
repository and connect it to
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 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 SedonaDB repository.
* Your fork is automatically configured as the **`origin`** remote.
```shell
diff --git a/docs/crs-examples.ipynb b/docs/crs-examples.ipynb
index 0548891..920f836 100644
--- a/docs/crs-examples.ipynb
+++ b/docs/crs-examples.ipynb
@@ -5,7 +5,7 @@
"id": "91910e50-a5ae-4d5a-a431-62ac5fbc11ca",
"metadata": {},
"source": [
- "# Joining Geospatial Data with Different CRSs.\n",
+ "# Joining Spatial Data with Different Coordinate Systems\n",
"\n",
"> Note: Before running this notebook, ensure that you have installed
SedonaDB: `pip install \"sedona[db]\"`\n",
"\n",
@@ -156,7 +156,7 @@
"id": "561b3c8c-4952-4fa7-9fe1-3fa0522b0d9f",
"metadata": {},
"source": [
- "### Join with mismatched CRSs\n",
+ "### Join with mismatched Coordinate Reference Systems\n",
"\n",
"The cities and countries tables have different CRSs.\n",
"\n",
@@ -293,7 +293,7 @@
"\n",
"The example highlights the following features:\n",
"\n",
- "1. SedonaDB reads the CRS stored in the files/\n",
+ "1. SedonaDB reads the CRS stored in the files.\n",
"2. SedonaDB protects you from accidentally joining files with mismatched
CRSs.\n",
"3. It's easy to convert a GeoPandas DataFrame to a SedonaDB DataFrame and
maintain the CRS."
]
diff --git a/docs/crs-examples.md b/docs/crs-examples.md
index 472469c..a5fbd02 100644
--- a/docs/crs-examples.md
+++ b/docs/crs-examples.md
@@ -17,7 +17,7 @@
under the License.
-->
-# Joining Geospatial Data with Different CRSs.
+# Joining Spatial Data with Different Coordinate Systems
> Note: Before running this notebook, ensure that you have installed SedonaDB:
> `pip install "sedona[db]"`
@@ -106,7 +106,7 @@ cities.to_view("cities", overwrite=True)
countries.to_view("countries", overwrite=True)
```
-### Join with mismatched CRSs
+### Join with mismatched Coordinate Reference Systems
The cities and countries tables have different CRSs.
@@ -138,7 +138,7 @@ where ST_Intersects(cities.geometry, countries.geometry)
----> 6 """).show()
- File ~/sedona-db/python/sedonadb/python/sedonadb/dataframe.py:380, in
DataFrame.show(self, limit, width, ascii)
+ File
~/sedona-db/sedona-db/python/sedonadb/python/sedonadb/dataframe.py:380, in
DataFrame.show(self, limit, width, ascii)
356 """Print the first limit rows to the console
357
358 Args:
@@ -214,7 +214,7 @@ This example shows how to join a `vermont` table with an
EPSG 32618 CRS with a `
The example highlights the following features:
-1. SedonaDB reads the CRS stored in the files/
+1. SedonaDB reads the CRS stored in the files.
2. SedonaDB protects you from accidentally joining files with mismatched CRSs.
3. It's easy to convert a GeoPandas DataFrame to a SedonaDB DataFrame and
maintain the CRS.
diff --git a/mkdocs.yml b/mkdocs.yml
index 314b68b..6b8babe 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -15,29 +15,58 @@
# specific language governing permissions and limitations
# under the License.
+extra:
+ version:
+ provider: mike
+ default:
+ - latest
+ social:
+ - icon: fontawesome/brands/github
+ link: 'https://github.com/apache/sedona-db/'
+ - icon: fontawesome/brands/twitter
+ link: 'https://twitter.com/ApacheSedona'
+ - icon: fontawesome/brands/discord
+ link: 'https://discord.gg/9A3k5dEBsY'
+ community_links: &community_links
+ - Get Involved:
+ - Sedona OSS Blog: "https://sedona.apache.org/latest/blog/";
+ - Community: "https://sedona.apache.org/latest/community/contact/";
+ - Apache Software Foundation:
"https://sedona.apache.org/latest/asf/asf/";
+
site_name: SedonaDB
-site_description: "Documentation for Apache SedonaDB"
+site_description: "Documentation for SedonaDB"
site_url: https://sedona.apache.org/sedonadb/
nav:
- - SedonaDB: index.md
- - Quickstart: quickstart-python.md
- - SedonaDB Guides:
- - Working with Vector Data: programming-guide.md
- - Working with GeoPandas: geopandas-interop.md
- - Working with Overture: overture-examples.md
- - Working with Parquet Files: working-with-parquet-files.md
- - Joining Geospatial Data with Different CRSs: crs-examples.md
- - Contributors Guide: contributors-guide.md
- - SedonaDB Reference:
+ # This becomes the 'SedonaDB' tab
+ - SedonaDB:
+ - Home: index.md
+ # The alias (*) works perfectly from the 'extra' block
+ - <<: *community_links
+
+ # This becomes the 'Quickstart' tab
+ - Python Quickstart:
+ - quickstart-python.md
+ - <<: *community_links
+
+ # This becomes the 'SedonaDB Guides' tab
+ - SedonaDB Guides:
+ - Working with Vector Data: programming-guide.md
+ - Working with GeoPandas: geopandas-interop.md
+ - Working with Overture: overture-examples.md
+ - Working with Parquet Files: working-with-parquet-files.md
+ - Contributors Guide: contributors-guide.md
+ - Joining Spatial Data with Different Coordinate Systems: crs-examples.md
+ - <<: *community_links
+
+ # This becomes the 'SedonaDB Reference' tab
+ - SedonaDB Reference:
- Python:
- Python Functions: reference/python.md
- SQL:
- SQL Functions: reference/sql.md
- Spatial Joins: reference/sql-joins.md
- - Blog: "https://sedona.apache.org/latest/blog/";
- - Community: "https://sedona.apache.org/latest/community/contact/";
- - Apache Software Foundation: "https://sedona.apache.org/latest/asf/asf/";
- - Sedona Homepage: "https://sedona.apache.org/latest/";
+ - <<: *community_links
+ - Sedona Homepage: "https://sedona.apache.org/";
repo_url: https://github.com/apache/sedona-db
edit_uri: https://github.com/apache/sedona-db/blob/main/docs/
@@ -67,11 +96,7 @@ theme:
- navigation.sections
- navigation.tabs
- navigation.tabs.sticky
-extra:
- version:
- provider: mike
- default:
- - latest
+
extra_css:
- stylesheets/extra.css
