Skip to content

Commit 31e932a

Browse files
niemyjskiniemyjski
committed
Build a real docs site and align sample/test surfaces
Root cause: the repo still exposed thin ad hoc documentation, public testing docs, and sample/test structure that had drifted from the current provider model and lacked dedicated docs validation.\n\nThis adds a VitePress docs site with provider playbooks, moves plan material out of docs, adds dedicated docs CI, aligns shared test namespaces/helpers with folder structure, and makes the sample advertise only providers that are actually usable under its configuration contract.
1 parent 6502975 commit 31e932a

39 files changed

Lines changed: 4447 additions & 58 deletions

‎.github/workflows/docs.yml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: Docs
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
9+
jobs:
10+
build-docs:
11+
runs-on: ubuntu-latest
12+
permissions:
13+
contents: read
14+
steps:
15+
- name: Checkout
16+
uses: actions/checkout@v6
17+
with:
18+
fetch-depth: 0
19+
20+
- name: Setup Node.js
21+
uses: actions/setup-node@v6
22+
with:
23+
node-version: 24
24+
25+
- name: Install dependencies
26+
working-directory: docs
27+
run: npm ci
28+
29+
- name: Build documentation
30+
working-directory: docs
31+
run: npm run build
32+
33+
- name: Upload artifact
34+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
35+
uses: actions/upload-pages-artifact@v4
36+
with:
37+
path: docs/.vitepress/dist
38+
39+
deploy-docs:
40+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
41+
needs: build-docs
42+
runs-on: ubuntu-latest
43+
permissions:
44+
contents: read
45+
pages: write
46+
id-token: write
47+
steps:
48+
- name: Setup Pages
49+
uses: actions/configure-pages@v5
50+
51+
- name: Deploy to GitHub Pages
52+
id: deployment
53+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,10 @@
22
/packages
33
/samples/packages
44
test/Geocoding.Tests/settings-override.json
5-
docs/plan.md
5+
docs/node_modules
6+
docs/.vitepress/cache
7+
docs/.vitepress/dist
8+
/plans/plan.md
69

710
.vs
811
/artifacts

‎AGENTS.md‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ Geocoding.net provides a unified interface for geocoding and reverse geocoding a
1010

1111
- **Core** (`Geocoding.Core`) - `IGeocoder` interface, `Address`, `Location`, distance calculations
1212
- **Google Maps** (`Geocoding.Google`) - Google Maps Geocoding API
13-
- **Bing Maps** (`Geocoding.Microsoft`) - Bing Maps / Virtual Earth API
13+
- **Microsoft** (`Geocoding.Microsoft`) - Azure Maps plus legacy Bing Maps compatibility
1414
- **HERE** (`Geocoding.Here`) - HERE Geocoding API
1515
- **MapQuest** (`Geocoding.MapQuest`) - MapQuest Geocoding API (commercial & OpenStreetMap)
1616
- **Yahoo** (`Geocoding.Yahoo`) - Yahoo BOSS Geo Services
@@ -38,10 +38,10 @@ src/
3838
├── Geocoding.Google # Google Maps geocoding provider
3939
├── Geocoding.Here # HERE geocoding provider
4040
├── Geocoding.MapQuest # MapQuest geocoding provider
41-
├── Geocoding.Microsoft # Bing Maps geocoding provider
41+
├── Geocoding.Microsoft # Azure Maps plus legacy Bing Maps compatibility
4242
└── Geocoding.Yahoo # Yahoo geocoding provider
4343
test/
44-
└── Geocoding.Tests # xUnit tests for all providers
44+
└── Geocoding.Tests # xUnit tests with provider-prefixed root tests plus folders for shared concerns
4545
samples/
4646
└── Example.Web # Sample web application
4747
```
@@ -77,7 +77,7 @@ samples/
7777
- **Async suffix**: All async methods end with `Async` (e.g., `GeocodeAsync`, `ReverseGeocodeAsync`)
7878
- **Provider-specific data**: Each provider exposes its own `Address` subclass with additional properties
7979
- **Exception types**: Each provider has its own exception type (e.g., `GoogleGeocodingException`, `BingGeocodingException`)
80-
- **JSON parsing**: Providers use `Newtonsoft.Json` for API response parsing
80+
- **JSON parsing**: Providers use `System.Text.Json` with the shared geocoding serializer helpers
8181

8282
## Making Changes
8383

@@ -132,6 +132,7 @@ Before marking work complete, verify:
132132
- **xUnit** as the primary testing framework
133133
- Tests cover all providers with shared base patterns (`GeocoderTest`, `AsyncGeocoderTest`)
134134
- Provider-specific tests extend base test classes
135+
- Keep provider-specific test files at the root of `test/Geocoding.Tests` with provider-prefixed names; use folders only for shared cross-cutting concerns such as `Models`, `Serialization`, `Extensions`, and `Utility`
135136
- For `HttpClient` failure-path tests, prefer `TestHttpMessageHandler.CreateResponse(...)` or `CreateResponseAsync(...)` instead of constructing `HttpResponseMessage` inline inside handler lambdas
136137

137138
### Running Tests

‎README.md‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,11 @@
22

33
Includes a model and interface for communicating with current geocoding providers.
44

5+
This repository is the actively maintained Geocoding.net fork for current provider integrations and compatibility work.
6+
57
| Provider | Package | Status | Auth | Notes |
68
| --- | --- | --- | --- | --- |
7-
| Google Maps | `Geocoding.Google` | Supported | API key or signed client credentials | `BusinessKey` supports signed Google Maps client-based requests when your deployment requires them. |
9+
| Google Maps | `Geocoding.Google` | Supported | API key or signed client credentials | `BusinessKey` remains available as a legacy signed-client compatibility path. |
810
| Azure Maps | `Geocoding.Microsoft` | Supported | Azure Maps subscription key | Primary Microsoft-backed geocoder. |
911
| Bing Maps | `Geocoding.Microsoft` | Deprecated compatibility | Bing Maps enterprise key | `BingMapsGeocoder` remains available for existing consumers and is marked obsolete for new development. |
1012
| HERE Geocoding and Search | `Geocoding.Here` | Supported | HERE API key | Uses the current HERE Geocoding and Search API. |
@@ -70,6 +72,8 @@ The Microsoft providers expose `AzureMapsAddress`, and the legacy `BingMapsGeoco
7072

7173
Google uses a [Geocoding API key](https://developers.google.com/maps/documentation/geocoding/get-api-key), and many environments now require one for reliable access.
7274

75+
If you still depend on signed Google Maps client credentials, `BusinessKey` remains available as a legacy compatibility option.
76+
7377
Azure Maps requires an [Azure Maps account key](https://learn.microsoft.com/en-us/azure/azure-maps/how-to-manage-account-keys#create-a-new-account).
7478

7579
Bing Maps requires an existing Bing Maps enterprise key. The provider is deprecated and retained only for compatibility during migration to Azure Maps.
@@ -99,6 +103,12 @@ You will need credentials for each respective service to run the service tests.
99103

100104
Most provider-backed integration tests skip with a message indicating which setting is required when credentials are missing. The Yahoo suite now follows the same credential gating, but the provider remains deprecated and unverified.
101105

106+
Provider-specific tests stay at the root of `test/Geocoding.Tests` with provider-prefixed filenames. Shared cross-cutting areas use focused folders such as `Models`, `Serialization`, `Extensions`, and `Utility`.
107+
108+
Provider-specific automated coverage exists for Google, Microsoft (Azure Maps and Bing compatibility), HERE, MapQuest, and Yahoo compatibility, alongside shared core behavior tests.
109+
110+
See the docs site in `docs/` for the provider guides, onboarding material, and sample app usage notes.
111+
102112
## Sample App
103113

104114
The sample app in `samples/Example.Web` is an ASP.NET Core 10 minimal API that can geocode and reverse geocode against any configured provider, including the deprecated Bing compatibility option when explicitly enabled. Yahoo remains excluded from the sample because the legacy provider still targets discontinued non-TLS endpoints.

‎docs/.vitepress/config.ts‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
import { defineConfig } from 'vitepress'
2+
import llmstxt from 'vitepress-plugin-llms'
3+
4+
export default defineConfig({
5+
title: 'Geocoding.net',
6+
description: 'Provider-agnostic geocoding documentation for consumers and contributors',
7+
base: '/Geocoding.net/',
8+
srcExclude: ['README.md'],
9+
vite: {
10+
plugins: [
11+
llmstxt({
12+
title: 'Geocoding.net Documentation',
13+
ignoreFiles: ['node_modules/**', '.vitepress/**']
14+
})
15+
]
16+
},
17+
head: [
18+
['meta', { name: 'theme-color', content: '#0f766e' }]
19+
],
20+
themeConfig: {
21+
nav: [
22+
{ text: 'Guide', link: '/guide/what-is-geocoding-net' },
23+
{ text: 'Providers', link: '/guide/providers' },
24+
{ text: 'GitHub', link: 'https://github.com/exceptionless/Geocoding.net' }
25+
],
26+
sidebar: {
27+
'/guide/': [
28+
{
29+
text: 'Introduction',
30+
items: [
31+
{ text: 'What is Geocoding.net?', link: '/guide/what-is-geocoding-net' },
32+
{ text: 'Getting Started', link: '/guide/getting-started' }
33+
]
34+
},
35+
{
36+
text: 'Providers',
37+
items: [
38+
{ text: 'Provider Overview', link: '/guide/providers' },
39+
{ text: 'Google Maps', link: '/guide/providers/google' },
40+
{ text: 'Azure Maps', link: '/guide/providers/azure-maps' },
41+
{ text: 'HERE', link: '/guide/providers/here' },
42+
{ text: 'MapQuest', link: '/guide/providers/mapquest' },
43+
{ text: 'Bing Maps Compatibility', link: '/guide/providers/bing-maps' },
44+
{ text: 'Yahoo Compatibility', link: '/guide/providers/yahoo' }
45+
]
46+
},
47+
{
48+
text: 'Operations',
49+
items: [
50+
{ text: 'Sample App', link: '/guide/sample-app' }
51+
]
52+
}
53+
]
54+
},
55+
socialLinks: [
56+
{ icon: 'github', link: 'https://github.com/exceptionless/Geocoding.net' }
57+
],
58+
footer: {
59+
message: 'Provider-agnostic geocoding for .NET.'
60+
},
61+
editLink: {
62+
pattern: 'https://github.com/exceptionless/Geocoding.net/edit/main/docs/:path'
63+
},
64+
search: {
65+
provider: 'local'
66+
}
67+
},
68+
markdown: {
69+
lineNumbers: false
70+
}
71+
})

‎docs/README.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Geocoding.net Documentation
2+
3+
This folder contains the VitePress documentation site for Geocoding.net.
4+
5+
## Prerequisites
6+
7+
- Node.js 20.19.x LTS or 22.12+
8+
- npm
9+
10+
## Getting Started
11+
12+
Install dependencies from the `docs/` directory:
13+
14+
```bash
15+
npm ci
16+
```
17+
18+
Start the development server:
19+
20+
```bash
21+
npm run dev
22+
```
23+
24+
Build the static site:
25+
26+
```bash
27+
npm run build
28+
```
29+
30+
Preview the built site locally:
31+
32+
```bash
33+
npm run preview
34+
```
35+
36+
## Structure
37+
38+
```text
39+
docs/
40+
├── .vitepress/
41+
│ └── config.ts
42+
├── guide/
43+
│ ├── getting-started.md
44+
│ ├── providers/
45+
│ │ ├── azure-maps.md
46+
│ │ ├── bing-maps.md
47+
│ │ ├── google.md
48+
│ │ ├── here.md
49+
│ │ ├── mapquest.md
50+
│ │ └── yahoo.md
51+
│ ├── providers.md
52+
│ ├── sample-app.md
53+
│ └── what-is-geocoding-net.md
54+
├── index.md
55+
├── package-lock.json
56+
├── package.json
57+
└── README.md
58+
```
59+
60+
## Notes
61+
62+
- `guide/` contains the published consumer and contributor documentation.
63+
- Keep `README.md`, `AGENTS.md`, and the guide pages aligned when provider support or contributor workflows change.

‎docs/guide/getting-started.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Getting Started
2+
3+
## Choose Packages
4+
5+
Install the provider package that matches the service you want to call. Each provider package references the shared core abstractions.
6+
7+
```powershell
8+
Install-Package Geocoding.Google
9+
Install-Package Geocoding.Microsoft
10+
Install-Package Geocoding.Here
11+
Install-Package Geocoding.MapQuest
12+
```
13+
14+
Install `Geocoding.Yahoo` only when you are maintaining a legacy compatibility flow.
15+
16+
## Pick a Starting Provider
17+
18+
- Start with Azure Maps when you want the actively supported Microsoft-backed provider.
19+
- Start with Google Maps when you need Google's result model or you already operate on Google Cloud.
20+
- Start with HERE or MapQuest when those services are already part of your stack.
21+
- Treat Bing Maps and Yahoo as compatibility paths, not default choices for new work.
22+
23+
## Forward Geocoding
24+
25+
```csharp
26+
using System.Collections.Generic;
27+
using System.Linq;
28+
using System.Threading;
29+
using Geocoding;
30+
using Geocoding.Google;
31+
32+
CancellationToken cancellationToken = default;
33+
IGeocoder geocoder = new GoogleGeocoder("your-google-api-key");
34+
IEnumerable<Address> addresses = await geocoder.GeocodeAsync(
35+
"1600 Pennsylvania Ave NW Washington DC 20500",
36+
cancellationToken);
37+
38+
Address first = addresses.First();
39+
Console.WriteLine(first.FormattedAddress);
40+
```
41+
42+
## Reverse Geocoding
43+
44+
```csharp
45+
using System.Collections.Generic;
46+
using System.Threading;
47+
using Geocoding;
48+
using Geocoding.Microsoft;
49+
50+
CancellationToken cancellationToken = default;
51+
IGeocoder geocoder = new AzureMapsGeocoder("your-azure-maps-key");
52+
IEnumerable<Address> addresses = await geocoder.ReverseGeocodeAsync(
53+
38.8976777,
54+
-77.036517,
55+
cancellationToken);
56+
```
57+
58+
## Provider-Specific Data
59+
60+
Provider packages expose address types with service-specific fields. For example, Google results can be queried using `GoogleAddressType`:
61+
62+
```csharp
63+
using System.Collections.Generic;
64+
using System.Linq;
65+
using System.Threading;
66+
using Geocoding.Google;
67+
68+
CancellationToken cancellationToken = default;
69+
GoogleGeocoder geocoder = new("your-google-api-key");
70+
IEnumerable<GoogleAddress> addresses = await geocoder.GeocodeAsync(
71+
"1600 Pennsylvania Ave NW Washington DC 20500",
72+
cancellationToken);
73+
74+
string? country = addresses
75+
.Where(address => !address.IsPartialMatch)
76+
.Select(address => address[GoogleAddressType.Country]?.LongName)
77+
.FirstOrDefault();
78+
```
79+
80+
## Signed Google Business Credentials
81+
82+
Use signed Google business credentials only when you already rely on that legacy deployment model.
83+
84+
```csharp
85+
using Geocoding.Google;
86+
87+
BusinessKey businessKey = new(
88+
"your-client-id",
89+
"your-url-signing-key");
90+
91+
GoogleGeocoder geocoder = new(businessKey);
92+
```
93+
94+
## Build from Source
95+
96+
```bash
97+
dotnet restore
98+
dotnet build Geocoding.slnx
99+
```
100+
101+
## Credentials
102+
103+
- Google Maps: API key, with `BusinessKey` retained only for signed-client compatibility.
104+
- Azure Maps: subscription key.
105+
- Bing Maps: enterprise key for deprecated compatibility scenarios.
106+
- HERE: API key for the current Geocoding and Search API.
107+
- MapQuest: developer API key.
108+
- Yahoo: legacy OAuth consumer key and secret.
109+
110+
Continue with [Provider Support](./providers) for credential setup links, provider-specific notes, and migration guidance.

0 commit comments

Comments
 (0)