V1.0.0

.github/workflows/docs.yml

@@ -1,4 +1,4 @@
-name: generate and publish docs
+name: build and publish site
 
 on:
   push:
@@ -21,26 +21,24 @@ jobs:
           aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
           aws-region: ${{ secrets.AWS_REGION }}
 
-      - name: Set up Python
-        uses: actions/setup-python@v5
+      - name: Set up Node
+        uses: actions/setup-node@v4
         with:
-          python-version: '3.11'
-          cache: 'pip'
+          node-version: 'lts/*'
+          cache: 'npm'
 
       - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip 
-          pip install hatch
+        run: npm ci
 
-      - name: Build docs
-        run: hatch run docs:build
+      - name: Build site
+        run: npm run build
 
       - name: s3 sync
         uses: jakejarvis/s3-sync-action@master
         with:
           args: --follow-symlinks --delete
         env:
-          SOURCE_DIR: 'site'
+          SOURCE_DIR: 'dist'
           AWS_S3_BUCKET: ${{ secrets.AWS_S3_BUCKET }}
           AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
           AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
@@ -53,4 +51,4 @@ jobs:
           PATHS: '/*'
           AWS_REGION: ${{ secrets.AWS_REGION }}
           AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
-          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

CHANGELOG.md

@@ -4,6 +4,8 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [1.0.0] - 2026-xx-xx
+
 ## [1.0.0rc3] - 2026-05-23
 
 **Breaking changes**

README.md

@@ -2,13 +2,10 @@
 
 The official Python SDK for the OpenAQ API.
 
-> :warning: OpenAQ python is still under active development and may be unstable until a v1.0.0 release
-
 [![PyPI - Version](https://img.shields.io/pypi/v/openaq.svg)](https://pypi.org/project/openaq)
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/openaq.svg)](https://pypi.org/project/openaq)
 ![Codecov](https://img.shields.io/codecov/c/github/openaq/openaq-python)
 ![Static Badge](https://img.shields.io/badge/type%20checked-mypy-039dfc)
-[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![slack](https://img.shields.io/badge/Slack-OpenAQ-blue?logo=slack&color=%23198cff
 )](https://join.slack.com/t/openaq/shared_invite/zt-yzqlgsva-v6McumTjy2BZnegIK9XCVw)
@@ -18,8 +15,8 @@ The official Python SDK for the OpenAQ API.
 ## Table of Contents
 
 - [Installation](#installation)
-- [Documentation](#documentation)
 - [License](#license)
+- [Development](#development)
 
 ## Installation
 
@@ -33,17 +30,15 @@ pip install openaq
 
 Documentation available at [python.openaq.org](https://python.openaq.org)
 
-Documentation can also be run locally using `hatch run docs:serve`
+Information on building documentation site locally can be found in [docs/README.md](./docs/README.md)
 
 ## License
 
 The source code is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
 
 ## Development
 
-Code is styled according to [black](https://github.com/psf/black), imports are
-sorted using [isort](https://pycqa.github.io/isort/), and code is linted using
-[ruff](https://github.com/astral-sh/ruff).
+Code is linted using [ruff](https://github.com/astral-sh/ruff).
 
 Codebase can be automatically formatted and linted by running:
 

docs/.gitignore

@@ -0,0 +1,23 @@
+# build output
+dist/
+# generated types
+.astro/
+
+styles
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store

docs/.nvmrc

@@ -0,0 +1 @@
+26

docs/.vale.ini

@@ -0,0 +1,11 @@
+StylesPath = styles
+
+MinAlertLevel = suggestion
+
+Packages = Google, write-good, Readability, MDX
+
+[*.md]
+BasedOnStyles = Google, Readability, write-good
+
+[*.mdx]
+BasedOnStyles = Google, Readability, write-good

docs/README.md

@@ -0,0 +1,27 @@
+# OpenAQ Python SDK Documentation Site
+
+This folder contains the source code for the official documentation site of
+the OpenAQ Python SDK. The site is built using [Astro](https://astro.build/) and
+the [Starlight](https://starlight.astro.build/) documentation template.
+
+---
+
+## Prerequisites
+
+Ensure you have [Node.js 26.x.x](https://nodejs.org/) installed.
+
+Project dependencies are managed with [pnpm](https://pnpm.io/).
+
+## Quick start
+
+Install the dependencies
+
+```sh
+pnpm install
+```
+
+Run the development server, which defaults to http://localhost:4321.
+
+```sh
+pnpm run dev
+```

docs/astro.config.mjs

@@ -0,0 +1,110 @@
+// @ts-check
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+import icon from 'astro-icon';
+
+export default defineConfig({
+  site: 'https://python.openaq.org',
+  integrations: [
+    starlight({
+      title: 'OpenAQ Python SDK',
+      social: [
+        {
+          icon: 'github',
+          label: 'GitHub',
+          href: 'https://github.com/openaq/openaq-python',
+        },
+      ],
+      components: {
+        Hero: './src/components/Hero.astro',
+      },
+      customCss: ['./src/assets/landing.css'],
+      sidebar: [
+        {
+          label: 'Introduction',
+          items: [
+            { label: 'About', slug: 'introduction/about' },
+            {
+              label: 'Navigating the docs',
+              slug: 'introduction/navigating-the-docs',
+            },
+            { label: 'Contributing', slug: 'introduction/contributing' },
+          ],
+        },
+        {
+          label: 'Getting started',
+          items: [
+            { label: 'Quick start', slug: 'getting-started/quick-start' },
+            { label: 'Client', slug: 'getting-started/client' },
+            { label: 'Pagination', slug: 'getting-started/pagination' },
+            { label: 'Exceptions', slug: 'getting-started/exceptions' },
+            { label: 'Responses', slug: 'getting-started/responses' },
+            { label: 'Resources', slug: 'getting-started/resources' },
+          ],
+        },
+        {
+          label: 'Resources',
+          items: [
+            { label: 'Locations', slug: 'resources/locations' },
+            { label: 'Sensors', slug: 'resources/sensors' },
+            { label: 'Measurements', slug: 'resources/measurements' },
+            { label: 'Licenses', slug: 'resources/licenses' },
+            { label: 'Manufacturers', slug: 'resources/manufacturers' },
+            { label: 'Instruments', slug: 'resources/instruments' },
+            { label: 'Parameters', slug: 'resources/parameters' },
+            { label: 'Providers', slug: 'resources/providers' },
+            { label: 'Owners', slug: 'resources/owners' },
+            { label: 'Countries', slug: 'resources/countries' },
+          ],
+        },
+        {
+          label: 'Advanced usage',
+          items: [
+            { label: 'Custom serialization', slug: 'advanced/json' },
+            { label: 'Logging', slug: 'advanced/logging' },
+            { label: 'Handling rate limits', slug: 'advanced/rate-limiting' },
+          ],
+        },
+        {
+          label: 'Common workflows',
+          items: [
+            {
+              label: 'Geospatial queries',
+              slug: 'guides/geospatial-queries',
+            },
+            {
+              label: 'Integrating with Pandas',
+              slug: 'guides/pandas',
+            },
+            {
+              label: 'Paging results',
+              slug: 'guides/paging-results',
+            },
+            {
+              label: 'Writing data to csv',
+              slug: 'guides/write-to-csv',
+            },
+            {
+              label: 'Querying measurements',
+              slug: 'guides/querying-measurements',
+            },
+
+          ],
+        },
+        {
+          label: 'Reference',
+          items: [
+            { label: 'Client', slug: 'reference/client' },
+            { label: 'Exceptions', slug: 'reference/exceptions' },
+          ],
+        },
+      ],
+    }),
+    icon({
+      include: {
+        mdi: ['emoticon-happy-outline', 'emoticon-sad-outline'],
+      },
+    }),
+  ],
+});