Merge pull request #6 from SOORAJTS2001/feat/readthedocs

SOORAJTS2001 · web-flow · commit 099223dfac82 · 2025-12-18T21:47:22.000+05:30
Add read the docs
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,22 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Optionally, but recommended,
+# declare the Python requirements required to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+    install:
+    - requirements: docs/requirements.txt
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/make.bat b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -0,0 +1,3 @@
+myst-parser
+sphinx
+sphinxawesome-theme
diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css
@@ -0,0 +1,5 @@
+/* Wrap long code lines instead of horizontal scroll */
+pre code {
+  white-space: pre-wrap;
+  word-break: break-word;
+}
diff --git a/docs/source/_static/img.png b/docs/source/_static/img.png
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -0,0 +1,47 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'python-gazetteer'
+copyright = '2025, Sooraj Sivadasan'
+author = 'Sooraj Sivadasan'
+release = 'v0.1.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "myst_parser",
+]
+
+templates_path = ['_templates']
+exclude_patterns = ["_build"]
+pygments_style = "one-dark"
+pygments_dark_style = "one-dark"
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinxawesome_theme"
+html_static_path = ['_static']
+html_theme_options = {
+    "show_prev_next": True,
+    "awesome_external_links": True,
+}
+html_css_files = [
+    "custom.css",
+]
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+html_sidebars = {
+  "**": ["sidebar_main_nav_links.html", "sidebar_toc.html"]
+}
+html_title = "Python Gazetteer"
diff --git a/docs/source/implementation/index.md b/docs/source/implementation/index.md
@@ -0,0 +1,51 @@
+# Implementation
+## Why it was made ?
+
+Latitude and longitude are precise but not meaningful on their own. Most systems and people reason in terms of places - cities, regions, and addresses, not raw coordinates. Converting lat - long into an address adds semantic context, making location data understandable, searchable, and actionable in real-world applications.
+
+This method of converting coordinates into sensible locations is known as reverse geocoding
+They are heavily used in almost every customer facing applications like delivery, travel booking etc
+
+Conventional way of doing was using commercial API's like Google Maps, Mapbox
+They are very much accurate, but costly in nature, also they come with various rate limits.
+For large data intensive applications this may incur as a limitation
+
+Hence, there are Offline Reverse Geocoding libraries, they would be completely offline, since it runs on your machine
+there would be no rate limiting
+But they come at a cost of accuracy, their normal working procedure is to use a large point based dataset
+(most likely cities) coordinates and finding the nearest neighbour from the given coordinates using algorithms like
+`KDTree` from scipy
+
+## Problem with the conventional approach
+Suppose we have a situation like this
+```{image} ../_static/img.png
+:alt: Reverse geocoding flow
+:width: 600px
+:align: center
+```
+Here, we are trying to find address of this given location (blue point), but the closes point
+to it is Lisbon, If you are naively using the nearest neighbour algorithm it is going to return
+the address of Lisbon, but that is wrong because the point is visibly inside the boundary of Vermount
+
+## Our approach
+Instead of focusing entirely on points, we would be considering boundaries also.
+- Step 1
+    - Find the nearest neighbouring boundaries from the given coordinate
+    - This could be done by computing the centroid of polygons and use `KDTree`
+      algorithm to get the nearest **boundaries**
+    - By default, the nearest 3 neighbours are considered
+
+- Step 2
+   - Check whether which boundary encloses the given point
+
+This approach gives a validation that the given point is actually inside that boundary
+
+## Challenges
+**Storage**: This is one of the biggest challenges faced, because boundary data is huge, but
+Geoboundaries provide their simplified geometries free and open source, even though the total size
+was around 1.5 GB, so it was converted to WKB and stored inside sqlite for querying and filtering, hence the overall
+size reduced to around 90 MB
+
+**Speed**: It was impractical to check boundary enclosure for every boundary there is, hence computed
+their centroid instead and use them for primary layer of filtering, and enclosure was validated
+on the fly, saving time and space
diff --git a/docs/source/index.md b/docs/source/index.md
@@ -0,0 +1,30 @@
+# Python Gazetteer
+
+A simple offline, fast and accurate boundary based reverse geocoding library in python
+
+<table>
+  <tbody>
+    <tr>
+      <td>Countries</td>
+      <td>210+</td>
+    </tr>
+    <tr>
+      <td>Boundaries</td>
+      <td>145,000+</td>
+    </tr>
+    <tr>
+      <td>Available Divisions</td>
+      <td>ADM0, ADM1, ADM2/ADM3</td>
+    </tr>
+  </tbody>
+</table>
+
+
+```{toctree}
+:caption: Important links
+:maxdepth: 3
+
+installation/index
+usage/index
+implementation/index
+```
diff --git a/docs/source/installation/index.md b/docs/source/installation/index.md
@@ -0,0 +1,16 @@
+# Installation Guide
+## How to install
+
+Python Gazetteer is available in PyPI and could be installed via
+```bash
+pip install python-gazetteer
+```
+Or one could visit the release page from [here](https://github.com/SOORAJTS2001/gazetteer/releases) and download the source code<br>
+
+This package is compatible with Python versions of `3.12` `3.13` and `3.14` and depends on
+following packages
+```md
+pydantic
+scipy
+shapely
+```
diff --git a/docs/source/usage/index.md b/docs/source/usage/index.md
@@ -0,0 +1,46 @@
+# Usage
+## How to use it
+There are mainly two modes of using it, they could be chosen according to the use cases
+
+`mode=1` for smaller dataset <br>
+`mode=2` for larger dataset above 100000+ pairs
+
+They are essentially spawning multiple process to enable parallel computation for larger dataset,
+**default value for `mode` is 1**
+
+```python
+from gazetteer import Gazetteer #import the library
+gz = Gazetteer() #gazetteer instance
+coordinates = [(-74.0060,40.7128),(76.2673,9.9312)] # list of tuples, in order longitude,latitude
+for data in gz.search(coordinates): # gz.search() returns a generator
+    print(data) # GeocoderResultBaseModel
+```
+
+```bash
+lat=40.7128 lon=-74.006 result=LocationBaseModel(lat=40.77488420403987, lon=-73.97077035729478, name='New York', admin1='United States', admin2='New York')
+lat=9.9312 lon=76.2673 result=LocationBaseModel(lat=9.96268442863286, lon=76.32995967426373, name='Kanayannur', admin1='India', admin2='Kerala')
+```
+
+for larger dataset
+```python
+from gazetteer import Gazetteer
+gz = Gazetteer(mode=2)
+```
+
+Make sure that you are providing  `coordinates` as list of tuples, in order of `(longitude,latitude)`, other wise
+it would return error
+
+Here `gz.search(coordinates)` returns a generator instead of a plain list, this helps to do computation on the fly,
+hence the code below doesn't have to wait for completing the computation of the entire dataset
+
+However, if having a one time list is required, one could do
+```python
+from gazetteer import Gazetteer
+gz = Gazetteer()
+coordinates = [(-74.0060,40.7128),(76.2673,9.9312)]
+data = list(gz.search(coordinates))
+print(data)
+```
+```bash
+[GeocoderResultBaseModel(lat=40.7128, lon=-74.006, result=LocationBaseModel(lat=40.77488420403987, lon=-73.97077035729478, name='New York', admin1='United States', admin2='New York')), GeocoderResultBaseModel(lat=9.9312, lon=76.2673, result=LocationBaseModel(lat=9.96268442863286, lon=76.32995967426373, name='Kanayannur', admin1='India', admin2='Kerala'))]
+```
diff --git a/pyproject.toml b/pyproject.toml
@@ -29,9 +29,22 @@ dev = [
     "pytest>=9.0.2",
     "ruff>=0.14.9",
 ]
+docs = [
+    "myst-parser>=4.0.1",
+    "sphinx>=8.2.3",
+    "sphinxawesome-theme>=5.3.2",
+]
 
 [tool.ruff]
 line-length = 150
+exclude=[
+    "docs/**"
+]
+
+[tool.ruff.format]
+exclude = [
+    "docs/**",
+]
 
 [tool.ruff.lint]
 select = ["E", "F", "W", "I", "UP", "B"]
diff --git a/uv.lock b/uv.lock

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+myst-parser`
	`2`	`+sphinx`
	`3`	`+sphinxawesome-theme`