Skip to content

Commit c0ccfa0

Browse files
pblottierepblottiere
authored
Merge pull request #20 from ThalesGroup/github_pages
Add docs for github pages
2 parents 6a20732 + 0309ab8 commit c0ccfa0

File tree

11 files changed

+190
-129
lines changed

11 files changed

+190
-129
lines changed

‎.github/workflows/build-deploy-docs.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
name: Documentation
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
pull_request:
7+
8+
jobs:
9+
build-docs:
10+
name: Build Docs
11+
runs-on: ubuntu-latest
12+
steps:
13+
- uses: actions/checkout@v4
14+
15+
- name: Setup mdBook
16+
uses: peaceiris/actions-mdbook@v1
17+
with:
18+
mdbook-version: 'latest'
19+
20+
- run: mdbook build docs
21+
22+
- name: Deploy
23+
uses: peaceiris/actions-gh-pages@v3
24+
if: github.ref == 'refs/heads/main'
25+
with:
26+
deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
27+
publish_branch: gh-pages
28+
publish_dir: ./docs/build

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
docs/build

‎README.md‎

Lines changed: 3 additions & 129 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
[![License](https://img.shields.io/github/license/ThalesGroup/PharoOWS.svg)](./LICENSE)
88
[![Unit tests](https://github.com/ThalesGroup/PharoOWS/actions/workflows/CI.yml/badge.svg)](https://github.com/ThalesGroup/PharoOWS/actions/workflows/CI.yml)
99

10+
1011
## :information_source: Get started
1112

1213
A variety of protocols and standards exist to enable communication with map
@@ -20,135 +21,9 @@ facto standards, offering tools for querying map servers and parsing the
2021
returned data.
2122

2223

23-
## :wrench: Install
24-
25-
PharoOWS can be installed using [Metacello](https://github.com/Metacello/metacello):
26-
27-
```smalltalk
28-
Metacello new
29-
baseline: 'OWS';
30-
repository: 'github://ThalesGroup/PharoOWS:main';
31-
load.
32-
```
33-
34-
Dependencies are:
35-
36-
- [XMLParser](https://github.com/pharo-contributions/XML-XMLParser)
37-
38-
39-
## :globe_with_meridians: Geospatial services: OGC Standards and de facto Protocols
40-
41-
Standard communication protocols with map servers can be divided into two main
42-
categories:
43-
44-
1. Official protocols defined by the Open Geospatial Consortium (OGC)
45-
2. De facto protocols that have emerged due to widespread use (such as XYZ)
46-
47-
### 1. Formal OGC protocols
48-
49-
**Traditional OGC Services**
50-
51-
These services are based on SOAP or HTTP protocols with specific requests often
52-
constructed as URLs with parameters. They primarily exchange XML or other
53-
specialized formats (XML for requests/responses, images for maps). These
54-
standards have been widely used for many years to ensure geospatial
55-
interoperability.
56-
57-
```console
58-
http://mapserver?SERVICE=WMS&REQUEST=GetMap&LAYERS=layer0,layer1
59-
```
60-
61-
**Modern RESTful Services**
62-
63-
These adopt a RESTful architecture based on modern web principles. They use
64-
simple HTTP methods (`GET`, `POST`, etc.) and return responses in JSON. This
65-
approach makes integration with applications easier due to its simplicity and
66-
compatibility with current web technologies. OGC API - Features is a key
67-
example of this new generation, providing standardized REST APIs for accessing
68-
vector data.
69-
70-
```console
71-
http://mapserver/collections/layer0/items.json
72-
```
73-
74-
### 2. De facto standards
75-
76-
Although not officially standardized by organizations like the OGC, protocols
77-
such as TMS (Tile Map Service) and the XYZ URL scheme are widely adopted in web
78-
mapping. Their simplicity and compatibility with modern web technologies have
79-
made them essential de facto standards for serving map tiles.
80-
24+
## :books: Documentation
8125

82-
## :package: PharoOWS : overview of supported protocols and standards
83-
84-
PharoOWS is split into several packages according to the supported protocols
85-
and standards:
86-
87-
| Package | Type | Supported Protocols | Status |
88-
|-------------------|-----------------------|-----------------------------------|------------------|
89-
| OWS-TMS | De facto standard | TMS | In development |
90-
| OWS-Service | Official OGC | WMS, WMTS | In development |
91-
| OWS-API | Official OGC (modern) | OGC API - Processes | Upcoming |
92-
93-
94-
:loudspeaker: PharoOWS is still in development, so new protocols and standards
95-
will be added over time.
96-
97-
## :computer: Examples
98-
99-
### WMS
100-
101-
```smalltalk
102-
| wms operations getmap layers size map |
103-
104-
"Create a WMS client targeting the IGN WMS server"
105-
wms := OWSServiceWMS new.
106-
wms url: 'https://data.geopf.fr/wms-r'.
107-
108-
"Introspect the server capabilities"
109-
operations := wms operations.
110-
111-
# 'operations' is a XMLOrderedList(
112-
# a OWSServiceWMSOperation <GetCapabilities>
113-
# a OWSServiceWMSOperation <GetMap>
114-
# a OWSServiceWMSOperation <GetFeatureInfo>
115-
# )
116-
117-
"Listing available image formats for maps"
118-
getmap := operations detect: [ :request | request name = 'GetMap' ].
119-
getmap formats.
120-
121-
# 'formats' is an OrderedCollection(
122-
# image/jpeg
123-
# image/png
124-
# image/tiff
125-
# image/geotiff
126-
# image/x-bil;bits=32
127-
# )
128-
129-
"Listing available layers"
130-
layers := wms layers.
131-
132-
# 'layers' is a XMLOrderedList(
133-
# a OWSServiceWMSLayer(ADMINEXPRESS-COG-CARTO.LATEST)
134-
# a OWSServiceWMSLayer(ADMINEXPRESS-COG.2017)
135-
# [...]
136-
# )
137-
138-
"Download a raster map with two layers for a bounding box defined by EPSG:3857 coordinates"
139-
map := wms
140-
map: { 'EL.GridCoverage'. 'FORETS.PUBLIQUES' }
141-
bbox: (-546079 @ 6126282 corner: -398839 @ 6212047)
142-
size: 800 @ 600
143-
epsg: '3857'
144-
format: 'image/png'.
145-
146-
# 'map' is a Bitmap
147-
```
148-
149-
<p align="center">
150-
<img src="doc/wms.png" alt="WMS map" width="400"/>
151-
</p>
26+
Documentation is available on Github pages.
15227

15328

15429
## :bust_in_silhouette: Contributing
@@ -161,4 +36,3 @@ If you are interested in contributing to the XXX project, start by reading the
16136

16237
This project is licensed under the MIT License - see the [LICENSE](LICENSE)
16338
file for details.
164-

‎docs/book.toml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
[book]
2+
authors = ["pblottiere"]
3+
language = "en"
4+
multilingual = false
5+
src = "src"
6+
title = "PharoOWS Documentation"
7+
8+
[build]
9+
build-dir = "./build"
10+
11+
[output.html]
12+
curly-quotes = true
13+
additional-css = ["custom.css"]
14+
git-repository-url = "https://github.com/ThalesGroup/PharoOWS"

‎docs/custom.css‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
:root {
2+
--content-max-width: 50%;
3+
}

‎docs/src/EXAMPLES.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Examples
2+
3+
## WMS
4+
5+
```` c++
6+
| wms operations getmap layers size map |
7+
8+
"Create a WMS client targeting the IGN WMS server"
9+
wms := OWSServiceWMS new.
10+
wms url: 'https://data.geopf.fr/wms-r'.
11+
12+
"Introspect the server capabilities"
13+
operations := wms operations.
14+
15+
# 'operations' is a XMLOrderedList(
16+
# a OWSServiceWMSOperation <GetCapabilities>
17+
# a OWSServiceWMSOperation <GetMap>
18+
# a OWSServiceWMSOperation <GetFeatureInfo>
19+
# )
20+
21+
"Listing available image formats for maps"
22+
getmap := operations detect: [ :request | request name = 'GetMap' ].
23+
getmap formats.
24+
25+
# 'formats' is an OrderedCollection(
26+
# image/jpeg
27+
# image/png
28+
# image/tiff
29+
# image/geotiff
30+
# image/x-bil;bits=32
31+
# )
32+
33+
"Listing available layers"
34+
layers := wms layers.
35+
36+
# 'layers' is a XMLOrderedList(
37+
# a OWSServiceWMSLayer(ADMINEXPRESS-COG-CARTO.LATEST)
38+
# a OWSServiceWMSLayer(ADMINEXPRESS-COG.2017)
39+
# [...]
40+
# )
41+
42+
"Download a raster map with two layers for a bounding box defined by EPSG:3857 coordinates"
43+
map := wms
44+
map: { 'EL.GridCoverage'. 'FORETS.PUBLIQUES' }
45+
bbox: (-546079 @ 6126282 corner: -398839 @ 6212047)
46+
size: 800 @ 600
47+
epsg: '3857'
48+
format: 'image/png'.
49+
50+
# 'map' is a Bitmap
51+
````
52+
53+
<img src="images/wms.png" width="400">

‎docs/src/INSTALL.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Install
2+
3+
PharoOWS can be installed using [Metacello](https://github.com/Metacello/metacello):
4+
5+
```` c++
6+
Metacello new
7+
baseline: 'OWS';
8+
repository: 'github://ThalesGroup/PharoOWS:main';
9+
load.
10+
````
11+
12+
Dependencies are:
13+
14+
* [XMLParser](https://github.com/pharo-contributions/XML-XMLParser)

‎docs/src/OGC.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Geospatial services: OGC Standards and de facto Protocols
2+
3+
Standard communication protocols with map servers can be divided into two main
4+
categories:
5+
6+
* Official protocols defined by the Open Geospatial Consortium (OGC)
7+
* De facto protocols that have emerged due to widespread use (such as XYZ)
8+
9+
10+
## Formal OGC protocols
11+
12+
**Traditional OGC Services**
13+
14+
These services are based on SOAP or HTTP protocols with specific requests often
15+
constructed as URLs with parameters. They primarily exchange XML or other
16+
specialized formats (XML for requests/responses, images for maps). These
17+
standards have been widely used for many years to ensure geospatial
18+
interoperability.
19+
20+
```` console
21+
http://mapserver?SERVICE=WMS&REQUEST=GetMap&LAYERS=layer0,layer1
22+
````
23+
24+
**Modern RESTful Services**
25+
26+
These adopt a RESTful architecture based on modern web principles. They use
27+
simple HTTP methods (GET, POST, etc.) and return responses in JSON. This
28+
approach makes integration with applications easier due to its simplicity and
29+
compatibility with current web technologies. OGC API - Features is a key
30+
example of this new generation, providing standardized REST APIs for accessing
31+
vector data.
32+
33+
```` console
34+
http://mapserver/collections/layer0/items.json
35+
````
36+
37+
38+
## De facto standards
39+
40+
Although not officially standardized by organizations like the OGC, protocols
41+
such as TMS (Tile Map Service) and the XYZ URL scheme are widely adopted in web
42+
mapping. Their simplicity and compatibility with modern web technologies have
43+
made them essential de facto standards for serving map tiles.

‎docs/src/README.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
## Welcome to PharoOWS documentation.
2+
3+
A variety of protocols and standards exist to enable communication with map
4+
servers and access geographic data in both raster and vector formats. Defined
5+
by the [Open Geospatial Consortium (OGC)](https://www.ogc.org/), these
6+
protocols are fondamental to ensure interoperability between clients and
7+
servers.
8+
9+
PharoOWS supports the official OGC protocols along with some widely adopted de
10+
facto standards, offering tools for querying map servers and parsing the
11+
returned data.
12+
13+
14+
## Overview of supported protocols and standards
15+
16+
PharoOWS is split into several packages according to the supported protocols
17+
and standards:
18+
19+
| Package | Type | Supported Protocols | Status |
20+
|---------------|-----------------------|---------------------|----------------|
21+
| OWS-TMS | De facto standard | TMS | In development |
22+
| OWS-Service | Official OGC | WMS, WMTS | In development |
23+
| OWS-API | Official OGC (modern) | OGC API - Processes | Upcoming |
24+
25+
26+
📢 PharoOWS is still in development, so new protocols and standards will be added over time.

‎docs/src/SUMMARY.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
[Introduction](README.md)
2+
3+
- [Install](INSTALL.md)
4+
- [OGC protocols and standards](OGC.md)
5+
- [Examples](EXAMPLES.md)

0 commit comments

Comments
 (0)