Cleaning up mdbook (#697)

A lot of book content cleanup, making it a bit shorter and "logical"
(whatever that even means)

To try, run `just mdbook`

README.md

@@ -14,11 +14,11 @@ See [Martin book](https://maplibre.org/martin/) for complete documentation.
 
 ![Martin](https://raw.githubusercontent.com/maplibre/martin/main/logo.png)
 
-## Requirements
+## Prerequisites
 
 If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended.
 
-## Installation
+## Binary Distributions
 
 You can download martin from [GitHub releases page](https://github.com/maplibre/martin/releases).
 
@@ -39,7 +39,7 @@ brew tap maplibre/martin https://github.com/maplibre/martin.git
 brew install maplibre/martin/martin
 ```
 
-You can also use [official Docker image](https://ghcr.io/maplibre/martin), and share configuration file from the host with the container via the `-v` param.  Config file is optional - you can let Martin auto-discover all sources e.g. by passing `DATABASE_URL` only.
+Martin is also available as a [Docker image](https://ghcr.io/maplibre/martin). You could either share a configuration file from the host with the container via the `-v` param, or you can let Martin auto-discover all sources e.g. by passing `DATABASE_URL` or specifying the .mbtiles/.pmtiles files.
 
 ```shell
 export PGPASSWORD=postgres  # secret!
@@ -81,13 +81,13 @@ martin --config config.yaml
 Martin data is available via the HTTP `GET` endpoints:
 
 | URL                                    | Description                                                                          |
-|----------------------------------------|-----------------------------------------------------------------------------------------------------------|
+|----------------------------------------|--------------------------------------------------------------------------------------|
 | `/`                                    | Status text, that will eventually show web UI                                        |
-| `/catalog`                             | [List of all sources](https://maplibre.org/martin/source-list.html)                                       |
+| `/catalog`                             | [List of all sources](https://maplibre.org/martin/using.html#catalog)                |
-| `/{sourceID}`                          | [Source TileJSON](https://maplibre.org/martin/table-sources.html#table-source-tilejson)                   |
+| `/{sourceID}`                          | [Source TileJSON](https://maplibre.org/martin/using.html#source-tilejson)            |
-| `/{sourceID}/{z}/{x}/{y}`              | [Source Tiles](https://maplibre.org/martin/table-sources.html#table-source-tiles)                         |
+| `/{sourceID}/{z}/{x}/{y}`              | Map Tiles                                                                            |
-| `/{sourceID1},...,{nameN}`             | [Composite Source TileJSON](https://maplibre.org/martin/composite-sources.html#composite-source-tilejson) |
+| `/{source1},...,{sourceN}`             | [Composite Source TileJSON](https://maplibre.org/martin/using.html#source-tilejson)  |
-| `/{sourceID1},...,{nameN}/{z}/{x}/{y}` | [Composite Source Tiles](https://maplibre.org/martin/composite-sources.html#composite-source-tiles)       |
+| `/{source1},...,{sourceN}/{z}/{x}/{y}` | [Composite Source Tiles](https://maplibre.org/martin/using.htmlsources-composite.md) |
 | `/health`                              | Martin server health check: returns 200 `OK`                                         |
 
 ## Documentation

docs/book.toml

@@ -1,9 +1,9 @@
 [book]
-authors = ["Maplibre"]
+authors = ["MapLibre contributors"]
 language = "en"
 multilingual = false
 src = "src"
-title = "Martin Documentation"
+title = "Martin Tile Server Documentation"
 
 [output.html]
 curly-quotes = true

docs/src/API.md

@@ -1,13 +0,0 @@
-# API
-
-Martin data is available via the HTTP `GET` endpoints:
-
-| URL                                    | Description                                                                                               |
-|----------------------------------------|-----------------------------------------------------------------------------------------------------------|
-| `/`                                    | Status text, that will eventually show web UI                                                             |
-| `/catalog`                             | [List of all sources](https://maplibre.org/martin/source-list.html)                                       |
-| `/{sourceID}`                          | [Source TileJSON](https://maplibre.org/martin/table-sources.html#table-source-tilejson)                   |
-| `/{sourceID}/{z}/{x}/{y}`              | [Source Tiles](https://maplibre.org/martin/table-sources.html#table-source-tiles)                         |
-| `/{sourceID1},...,{nameN}`             | [Composite Source TileJSON](https://maplibre.org/martin/composite-sources.html#composite-source-tilejson) |
-| `/{sourceID1},...,{nameN}/{z}/{x}/{y}` | [Composite Source Tiles](https://maplibre.org/martin/composite-sources.html#composite-source-tiles)       |
-| `/health`                              | Martin server health check: returns 200 `OK`                                                              |

docs/src/SUMMARY.md

@@ -1,99 +1,23 @@
-# Summary
-
 [Introduction](introduction.md)
-
-# Requirements
-
-- [Requirements](requirements.md)
-
-# Installation
-
 - [Installation](installation.md)
-
+  - [Building from Source](building-from-source.md)
-# Usage
+- [Running](run.md)
-
+  - [Command Line Interface](run-with-cli.md)
-- [Usage](usage.md)
+    - [Environment Variables](env-vars.md)
-
+  - [Running with Docker](run-with-docker.md)
-# API
+  - [Running with Docker Compose](run-with-docker-compose.md)
-
+  - [Running with NGINX](run-with-nginx.md)
-- [API](API.md)
+  - [Troubleshooting](troubleshooting.md)
-
+- [Configuration File](config-file.md)
-# Using with MapLibre
+  - [PostgreSQL Connections](pg-connections.md)
-
+  - [PostgreSQL Table Sources](sources-pg-tables.md)
-- [Using with MapLibre](using-with-MapLibre.md)
+  - [PostgreSQL Function Sources](sources-pg-functions.md)
-
+  - [MBTiles and PMTiles File Sources](sources-files.md)
-# Using with Leaflet
+  - [Composite Sources](sources-composite.md)
-
+- [Usage and Endpoint API](using.md)
-- [Using with Leaflet](using-with-Leaflet.md)
+  - [Using with MapLibre](using-with-maplibre.md)
-
+  - [Using with Leaflet](using-with-leaflet.md)
-# Using with deck.gl
+  - [Using with deck.gl](using-with-deck-gl.md)
-
+  - [Using with Mapbox](using-with-mapbox.md)
-- [Using with deck.gl](using-with-deck.gl.md)
-
-# Using with Mapbox
-
-- [Using with Mapbox](using-with-Mapbox.md)
-
-# Source List
-
-- [Source List](source-list.md)
-
-# Table Sources
-
-- [Table Sources](table-sources.md)
-
-# Composite Sources
-
-- [Composite Sources](composite-sources.md)
-
-# Function Sources
-
-- [Function Sources](function-Sources.md)
-
-# MBTile and PMTile Sources
-
-- [MBTile and PMTile Sources](MBTile-and-PMTile-Sources.md)
-
-# Command-line Interface
-
-- [Command-line Interface](command-line-Interface.md)
-
-# Environment Variables
-
-- [Environment Variables](environment-Variables.md)
-
-# Configuration File
-
-- [Configuration File](configuration-File.md)
-
-# PostgreSQL Connection String
-
-- [PostgreSQL Connection String](PostgreSQL-Connection-String.md)
-
-# Using with Docker
-
-- [Using with Docker](using-with-Docker.md)
-
-# Using with Docker Compose
-
-- [Using with Docker Compose](using-with-Docker-Compose.md)
-
-# Using with Nginx
-
-- [Using with Nginx](using-with-Nginx.md)
-
-# Building from Source
-
-- [Building from Source](building-from-Source.md)
-
-# Debugging
-
-- [Debugging](debugging.md)
-
-# Development
-
-- [Development](development.md)
-
-# Recipes
-
   - [Recipes](recipes.md)
+- [Development](development.md)

docs/src/config-file.md

@@ -8,6 +8,12 @@ martin --config config.yaml
 
 You may wish to auto-generate a config file with `--save-config` argument. This will generate a config yaml file with all of your configuration, which you can edit to remove any sources you don't want to expose.
 
+```shell
+martin  ... ... ...  --save-config config.yaml
+```
+
+## Config Example
+
 ```yaml
 # Connection keep alive timeout [default: 75]
 keep_alive: 75
@@ -45,7 +51,8 @@ postgres:
   # If enabled, it will spend some time on startup to compute geometry bounds.
   disable_bounds: false
 
-  # Enable automatic discovery of tables and functions. You may set this to `false` to disable.
+  # Enable automatic discovery of tables and functions.
+  # You may set this to `false` to disable.
   auto_publish:
     # Optionally limit to just these schemas
     from_schemas:

docs/src/development.md

@@ -1,12 +1,34 @@
 # Development
 
-* Clone Martin
+Clone Martin, setting remote name to `upstream`. This way `main` branch will be updated automatically with the latest changes from the upstream repo.
-* Install [docker](https://docs.docker.com/get-docker/), [docker-compose](https://docs.docker.com/compose/), and [Just](https://github.com/casey/just#readme) (improved makefile processor)
+```shell, ignore
-* Run `just` to see available commands:
+git clone git@github.com:maplibre/martin.git -o upstream
+cd martin
+```
+
+Fork Martin repo into your own GitHub account, and add your fork as a remote
+
+```shell, ignore
+git remote add origin <your_fork_url>
+```
+
+Install [docker](https://docs.docker.com/get-docker/), [docker-compose](https://docs.docker.com/compose/), and openssl:
+
+```shell, ignore
+# For Ubuntu-based distros
+sudo apt install -y  docker.io  docker-compose  libssl-dev
+```
+
+
+Install [Just](https://github.com/casey/just#readme) (improved makefile processor). Note that some Linux and Homebrew distros have outdated versions of Just, so you should install it from source:
+
+```shell, ignore
+cargo install just
+```
+
+When developing MBTiles SQL code, you may need to use `just prepare-sqlite` whenever SQL queries are modified. Run `just` to see all available commands:
 
 ```shell, ignore
-❯ git clone git@github.com:maplibre/martin.git
-❯ cd martin
 ❯ just
 Available recipes:
     run *ARGS              # Start Martin server and a test database
@@ -24,10 +46,13 @@ Available recipes:
     test-unit *ARGS        # Run Rust unit and doc tests (cargo test)
     test-int               # Run integration tests
     bless                  # Run integration tests and save its output as the new expected output
+    mdbook                 # Build and open mdbook documentation
+    docs                   # Build and open code documentation
     coverage FORMAT='html' # Run code coverage on tests and save its output in the coverage directory. Parameter could be html or lcov.
     docker-build           # Build martin docker image
     docker-run *ARGS       # Build and run martin docker image
     git *ARGS              # Do any git command, ensuring that the testing environment is set up. Accepts the same arguments as git.
     print-conn-str         # Print the connection string for the test database
     lint                   # Run cargo fmt and cargo clippy
+    prepare-sqlite         # Update sqlite database schema. Install SQLX cli if not already installed.
 ```

docs/src/env-vars.md

@@ -1,6 +1,6 @@
 # Environment Variables
 
-You can also configure Martin using environment variables, but only if the configuration file is not used. See [configuration section](#configuration-file) on how to use environment variables with config files. See also [SSL configuration](#postgresql-ssl-connections) section below.
+You can also configure Martin using environment variables, but only if the configuration file is not used. See [configuration section](config-file.md) on how to use environment variables with config files. See also [SSL configuration](pg-connections.md#postgresql-ssl-connections) section below.
 
 | Environment var <br/> Config File key    | Example                              | Description                                                                                                                                                                                                                                                                                            |
 |------------------------------------------|--------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

docs/src/installation.md

@@ -1,4 +1,8 @@
-# Installation
+## Prerequisites
+
+If using Martin with PostgreSQL database, you must install PostGIS with at least v3.0+, v3.1+ recommended.
+
+## Binary Distributions
 
 You can download martin from [GitHub releases page](https://github.com/maplibre/martin/releases).
 
@@ -12,6 +16,8 @@ You can download martin from [GitHub releases page](https://github.com/maplibre/
 [rl-macos-tar]: https://github.com/maplibre/martin/releases/latest/download/martin-Darwin-x86_64.tar.gz
 [rl-win64-zip]: https://github.com/maplibre/martin/releases/latest/download/martin-Windows-x86_64.zip
 
+## Homebrew
+
 If you are using macOS and [Homebrew](https://brew.sh/) you can install martin using Homebrew tap.
 
 ```shell
@@ -19,24 +25,15 @@ brew tap maplibre/martin https://github.com/maplibre/martin.git
 brew install maplibre/martin/martin
 ```
 
-You can also use [official Docker image](https://ghcr.io/maplibre/martin)
+## Docker
+
+Martin is also available as a [Docker image](https://ghcr.io/maplibre/martin). You could either share a configuration file from the host with the container via the `-v` param, or you can let Martin auto-discover all sources e.g. by passing `DATABASE_URL` or specifying the .mbtiles/.pmtiles files.
 
 ```shell
 export PGPASSWORD=postgres  # secret!
-docker run \
+docker run -p 3000:3000 \
-       -p 3000:3000 \
            -e PGPASSWORD \
-       -e DATABASE_URL=postgresql://postgres@localhost/db \
+           -e DATABASE_URL=postgresql://user@host:port/db \
-       ghcr.io/maplibre/martin
+           -v /path/to/config/dir:/config \
-```
-
-Use docker `-v` param to share configuration file or its directory with the container:
-
-```shell
-export PGPASSWORD=postgres  # secret!
-docker run -v /path/to/config/dir:/config \
-           -p 3000:3000 \
-           -e PGPASSWORD \
-           -e DATABASE_URL=postgresql://postgres@localhost/db \
            ghcr.io/maplibre/martin --config /config/config.yaml
 ```

docs/src/introduction.md

@@ -1,10 +1,13 @@
-# Introduction
-
-<h1>Martin</h1>
-
-[![CI](https://github.com/maplibre/martin/workflows/CI/badge.svg)](https://github.com/maplibre/martin/actions)
-![Security audit](https://github.com/maplibre/martin/workflows/Security%20audit/badge.svg)
-
-Martin is a tile server able to generate [vector tiles](https://github.com/mapbox/vector-tile-spec) from large [PostGIS](https://github.com/postgis/postgis) databases on the fly, or serve tiles from [PMTile](https://protomaps.com/blog/pmtiles-v3-whats-new) and [MBTile](https://github.com/mapbox/mbtiles-spec) files. Martin optimizes for speed and heavy traffic, and is written in [Rust](https://github.com/rust-lang/rust).
-
 ![Martin](https://raw.githubusercontent.com/maplibre/martin/main/logo.png)
+
+Martin is a tile server able to generate and serve [vector tiles](https://github.com/mapbox/vector-tile-spec) on the fly from large [PostGIS](https://github.com/postgis/postgis) databases, [PMTiles](https://protomaps.com/blog/pmtiles-v3-whats-new), and [MBTiles](https://github.com/mapbox/mbtiles-spec) files, allowing multiple tile sources to be dynamically combined into one. Martin optimizes for speed and heavy traffic, and is written in [Rust](https://github.com/rust-lang/rust).
+
+---
+
+[![Book](https://img.shields.io/badge/docs-Book-informational)](https://maplibre.org/martin)
+[![docs.rs docs](https://docs.rs/martin/badge.svg)](https://docs.rs/martin)
+[![Slack chat](https://img.shields.io/badge/Chat-on%20Slack-blueviolet)](https://slack.openstreetmap.us/)
+[![GitHub](https://img.shields.io/badge/github-maplibre/martin-8da0cb?logo=github)](https://github.com/maplibre/martin)
+[![crates.io version](https://img.shields.io/crates/v/martin.svg)](https://crates.io/crates/martin)
+[![Security audit](https://github.com/maplibre/martin/workflows/Security%20audit/badge.svg)](https://github.com/maplibre/martin/security)
+[![CI build](https://github.com/maplibre/martin/workflows/CI/badge.svg)](https://github.com/maplibre/martin/actions)

docs/src/pg-connections.md

@@ -1,7 +1,9 @@
 # PostgreSQL Connection String
+
 Martin supports many of the PostgreSQL connection string settings such as `host`, `port`, `user`, `password`, `dbname`, `sslmode`, `connect_timeout`, `keepalives`, `keepalives_idle`, etc. See the [PostgreSQL docs](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING) for more details.
-`
+
 ## PostgreSQL SSL Connections
-Martin supports PostgreSQL `sslmode` including `disable`, `prefer`, `require`, `verify-ca` and `verify-full` modes as described in the [PostgreSQL docs](https://www.postgresql.org/docs/current/libpq-ssl.html).  Certificates can be provided in the configuration file, or can be set using the same env vars as used for `psql`. When set as env vars, they apply to all PostgreSQL connections.  See [environment vars](#environment-variables) section for more details.
+
+Martin supports PostgreSQL `sslmode` including `disable`, `prefer`, `require`, `verify-ca` and `verify-full` modes as described in the [PostgreSQL docs](https://www.postgresql.org/docs/current/libpq-ssl.html).  Certificates can be provided in the configuration file, or can be set using the same env vars as used for `psql`. When set as env vars, they apply to all PostgreSQL connections.  See [environment vars](env-vars.md) section for more details.
 
 By default, `sslmode` is set to `prefer` which means that SSL is used if the server supports it, but the connection is not aborted if the server does not support it.  This is the default behavior of `psql` and is the most compatible option.  Use the `sslmode` param to set a different `sslmode`, e.g. `postgresql://user:password@host/db?sslmode=require`.

docs/src/recipes.md

@@ -1,4 +1,3 @@
-# Recipes
 ## Using with DigitalOcean PostgreSQL
 
 You can use Martin with [Managed PostgreSQL from DigitalOcean](https://www.digitalocean.com/products/managed-databases-postgresql/) with PostGIS extension
@@ -6,7 +5,8 @@ You can use Martin with [Managed PostgreSQL from DigitalOcean](https://www.digit
 First, you need to download the CA certificate and get your cluster connection string from the [dashboard](https://cloud.digitalocean.com/databases). After that, you can use the connection string and the CA certificate to connect to the database
 
 ```shell
-martin --ca-root-file ./ca-certificate.crt postgresql://user:password@host:port/db?sslmode=require
+martin --ca-root-file ./ca-certificate.crt \
+       postgresql://user:password@host:port/db?sslmode=require
 ```
 
 ## Using with Heroku PostgreSQL

docs/src/requirements.md

@@ -1,3 +0,0 @@
-# Requirements
-
-Martin requires PostGIS 3.0+.  PostGIS 3.1+ is recommended.

docs/src/run-with-docker-compose.md

@@ -1,4 +1,4 @@
-# Using with Docker Compose
+# Running with Docker Compose
 
 You can use example [`docker-compose.yml`](https://raw.githubusercontent.com/maplibre/martin/main/docker-compose.yml) file as a reference
 

docs/src/run-with-docker.md

@@ -1,4 +1,4 @@
-# Using with Docker
+# Running with Docker
 
 You can use official Docker image [`ghcr.io/maplibre/martin`](https://ghcr.io/maplibre/martin)
 

docs/src/run-with-nginx.md

@@ -1,6 +1,6 @@
-# Using with Nginx
+# Using with NGINX
 
-You can run Martin behind Nginx proxy, so you can cache frequently accessed tiles and reduce unnecessary pressure on the database.
+You can run Martin behind NGINX proxy, so you can cache frequently accessed tiles and reduce unnecessary pressure on the database. Here is an example `docker-compose.yml` file that runs Martin with NGINX and PostgreSQL.
 
 ```yml
 version: '3'
@@ -36,11 +36,11 @@ services:
       - ./pg_data:/var/lib/postgresql/data
 ```
 
-You can find an example Nginx configuration file [here](https://github.com/maplibre/martin/blob/main/nginx.conf).
+You can find an example NGINX configuration file [here](https://github.com/maplibre/martin/blob/main/nginx.conf).
 
 ## Rewriting URLs
 
-If you are running Martin behind Nginx proxy, you may want to rewrite the request URL to properly handle tile URLs in [TileJSON](#table-source-tilejson) [endpoints](#function-source-tilejson).
+If you are running Martin behind NGINX proxy, you may want to rewrite the request URL to properly handle tile URLs in [TileJSON](using.md#source-tilejson).
 
 ```nginx
 location ~ /tiles/(?<fwd_path>.*) {
@@ -55,7 +55,7 @@ location ~ /tiles/(?<fwd_path>.*) {
 
 ## Caching tiles
 
-You can also use Nginx to cache tiles. In the example, the maximum cache size is set to 10GB, and caching time is set to 1 hour for responses with codes 200, 204, and 302 and 1 minute for responses with code 404.
+You can also use NGINX to cache tiles. In the example, the maximum cache size is set to 10GB, and caching time is set to 1 hour for responses with codes 200, 204, and 302 and 1 minute for responses with code 404.
 
 ```nginx
 http {
@@ -91,4 +91,4 @@ http {
 }
 ```
 
-You can find an example Nginx configuration file [here](https://github.com/maplibre/martin/blob/main/nginx.conf).
+You can find an example NGINX configuration file [here](https://github.com/maplibre/martin/blob/main/nginx.conf).

docs/src/run.md

@@ -1,6 +1,6 @@
 # Usage
 
-Martin requires at least one PostgreSQL [connection string](#postgresql-connection-string) or a [tile source file](#mbtile-and-pmtile-sources) as a command-line argument. A PG connection string can also be passed via the `DATABASE_URL` environment variable.
+Martin requires at least one PostgreSQL [connection string](pg-connections.md) or a [tile source file](sources-files.md) as a command-line argument. A PG connection string can also be passed via the `DATABASE_URL` environment variable.
 
 ```shell
 martin postgresql://postgres@localhost/db

docs/src/source-list.md

@@ -1,21 +0,0 @@
-# Source List
-
-A list of all available sources is available in a catalogue:
-
-```shell
-curl localhost:3000/catalog | jq
-```
-
-```yaml
-[
-  {
-    "id": "function_zxy_query",
-    "name": "public.function_zxy_query"
-  },
-  {
-    "id": "points1",
-    "name": "public.points1.geom"
-  },
-  ...
-]
-```

docs/src/sources-composite.md

@@ -4,22 +4,14 @@ Composite Sources allows combining multiple sources into one. Composite Source c
 
 Each source in a composite source can be accessed with its `{source_name}` as a `source-layer` property.
 
-## Composite Source TileJSON
+Composite source [TileJSON](https://github.com/mapbox/tilejson-spec) endpoint is available at `/{source1},...,{sourceN}`, and tiles are available at `/{source1},...,{sourceN}/{z}/{x}/{y}`.
-
-Composite Source [TileJSON](https://github.com/mapbox/tilejson-spec) endpoint is available at `/{source1},...,{sourceN}`.
-
-For example, composite source combining `points` and `lines` sources will be available at `/points,lines`
-
-```shell
-curl localhost:3000/points,lines | jq
-```
-
-## Composite Source Tiles
-
-Composite Source tiles endpoint is available at `/{source1},...,{sourceN}/{z}/{x}/{y}`
 
 For example, composite source combining `points` and `lines` sources will be available at `/points,lines/{z}/{x}/{y}`
 
 ```shell
+# TileJSON
+curl localhost:3000/points,lines
+
+# Whole world as a single tile
 curl localhost:3000/points,lines/0/0/0
 ```

docs/src/sources-files.md

@@ -1,4 +1,4 @@
-# MBTile and PMTile Sources
+# MBTiles and PMTiles File Sources
 
 Martin can serve any type of tiles from [PMTile](https://protomaps.com/blog/pmtiles-v3-whats-new) and [MBTile](https://github.com/mapbox/mbtiles-spec) files.  To serve a file from CLI, simply put the path to the file or the directory with `*.mbtiles` or `*.pmtiles` files. For example:
 
@@ -6,5 +6,4 @@ Martin can serve any type of tiles from [PMTile](https://protomaps.com/blog/pmti
 martin  /path/to/mbtiles/file.mbtiles  /path/to/directory
 ```
 
-You may also want to generate a [config file](#configuration-file) using the `--save-config my-config.yaml`, and later edit it and use it with `--config my-config.yaml` option.
+You may also want to generate a [config file](config-file.md) using the `--save-config my-config.yaml`, and later edit it and use it with `--config my-config.yaml` option.
-

docs/src/sources-pg-functions.md

@@ -1,4 +1,4 @@
-# Function Sources
+# PostgreSQL Function Sources
 
 Function Source is a database function which can be used to query [vector tiles](https://github.com/mapbox/vector-tile-spec). When started, Martin will look for the functions with a suitable signature. A function that takes `z integer` (or `zoom integer`), `x integer`, `y integer`, and an optional `query json` and returns `bytea`, can be used as a Function Source. Alternatively the function could return a record with a single `bytea` field, or a record with two fields of types `bytea` and `text`, where the `text` field is an etag key (i.e. md5 hash).
 
@@ -9,16 +9,22 @@ Function Source is a database function which can be used to query [vector tiles]
 | y                          | integer | Tile y parameter        |
 | query (optional, any name) | json    | Query string parameters |
 
+## Simple Function
 For example, if you have a table `table_source` in WGS84 (`4326` SRID), then you can use this function as a Function Source:
 
 ```sql, ignore
-CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer) RETURNS bytea AS $$
+CREATE OR REPLACE
+    FUNCTION function_zxy_query(z integer, x integer, y integer)
+    RETURNS bytea AS $$
 DECLARE
   mvt bytea;
 BEGIN
   SELECT INTO mvt ST_AsMVT(tile, 'function_zxy_query', 4096, 'geom') FROM (
     SELECT
-      ST_AsMVTGeom(ST_Transform(ST_CurveToLine(geom), 3857), ST_TileEnvelope(z, x, y), 4096, 64, true) AS geom
+      ST_AsMVTGeom(
+          ST_Transform(ST_CurveToLine(geom), 3857),
+          ST_TileEnvelope(z, x, y),
+          4096, 64, true) AS geom
     FROM table_source
     WHERE geom && ST_Transform(ST_TileEnvelope(z, x, y), 4326)
   ) as tile WHERE geom IS NOT NULL;
@@ -28,14 +34,24 @@ END
 $$ LANGUAGE plpgsql IMMUTABLE STRICT PARALLEL SAFE;
 ```
 
+## Function with Query Parameters
+Users may add a `query` parameter to pass additional parameters to the function.
+
+_**TODO**: Modify this example to actually use the query parameters._
+
 ```sql, ignore
-CREATE OR REPLACE FUNCTION function_zxy_query(z integer, x integer, y integer, query_params json) RETURNS bytea AS $$
+CREATE OR REPLACE
+    FUNCTION function_zxy_query(z integer, x integer, y integer, query_params json)
+    RETURNS bytea AS $$
 DECLARE
   mvt bytea;
 BEGIN
   SELECT INTO mvt ST_AsMVT(tile, 'function_zxy_query', 4096, 'geom') FROM (
     SELECT
-      ST_AsMVTGeom(ST_Transform(ST_CurveToLine(geom), 3857), ST_TileEnvelope(z, x, y), 4096, 64, true) AS geom
+      ST_AsMVTGeom(
+          ST_Transform(ST_CurveToLine(geom), 3857),
+          ST_TileEnvelope(z, x, y),
+          4096, 64, true) AS geom
     FROM table_source
     WHERE geom && ST_Transform(ST_TileEnvelope(z, x, y), 4326)
   ) as tile WHERE geom IS NOT NULL;
@@ -45,7 +61,13 @@ END
 $$ LANGUAGE plpgsql IMMUTABLE STRICT PARALLEL SAFE;
 ```
 
-The `query_params` argument is a JSON representation of the tile request query params. For example, if user requested a tile with [urlencoded](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) params:
+The `query_params` argument is a JSON representation of the tile request query params.  Query params could be passed as simple query values, e.g.
+
+```shell
+curl localhost:3000/function_zxy_query/0/0/0?token=martin
+```
+
+You can also use [urlencoded](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) params to encode complex values:
 
 ```shell
 curl \
@@ -74,23 +96,3 @@ You can access this params using [json operators](https://www.postgresql.org/doc
 ```sql, ignore
 ...WHERE answer = (query_params->'objectParam'->>'answer')::int;
 ```
-
-## Function Source TileJSON
-
-Function Source [TileJSON](https://github.com/mapbox/tilejson-spec) endpoint is available at `/{function_name}`
-
-For example, `points` function will be available at `/points`
-
-```shell
-curl localhost:3000/points | jq
-```
-
-## Function Source Tiles
-
-Function Source tiles endpoint is available at `/{function_name}/{z}/{x}/{y}`
-
-For example, `points` function will be available at `/points/{z}/{x}/{y}`
-
-```shell
-curl localhost:3000/points/0/0/0
-```

docs/src/sources-pg-tables.md

@@ -0,0 +1,3 @@
+# Table Sources
+
+Table Source is a database table which can be used to query [vector tiles](https://github.com/mapbox/vector-tile-spec). If a [PostgreSQL connection string](pg-connections.md) is given, Martin will publish all tables as data sources if they have at least one geometry column. If geometry column SRID is 0, a default SRID must be set, or else that geo-column/table will be ignored. All non-geometry table columns will be published as vector tile feature tags (properties).

docs/src/table-sources.md

@@ -1,29 +0,0 @@
-# Table Sources
-
-Table Source is a database table which can be used to query [vector tiles](https://github.com/mapbox/vector-tile-spec). When started, Martin will go through all spatial tables in the database and build a list of table sources. A table should have at least one geometry column with non-zero SRID. All other table columns except geometry will be properties of a vector tile feature.
-
-## Table Source TileJSON
-
-Table Source [TileJSON](https://github.com/mapbox/tilejson-spec) endpoint is available at `/{table_name}`.
-
-For example, `points` table will be available at `/points`, unless there is another source with the same name, or if the table has multiple geometry columns, in which case it will be available at `/points`, `/points.1`, etc.
-
-```shell
-curl localhost:3000/points | jq
-```
-
-## Table Source Tiles
-
-Table Source tiles endpoint is available at `/{table_name}/{z}/{x}/{y}`
-
-For example, `points` table will be available at `/points/{z}/{x}/{y}`
-
-```shell
-curl localhost:3000/points/0/0/0
-```
-
-In case if you have multiple geometry columns in that table and want to access a particular geometry column in vector tile, you should also specify the geometry column in the table source name
-
-```shell
-curl localhost:3000/points.geom/0/0/0
-```

docs/src/troubleshooting.md

@@ -1,4 +1,4 @@
-# Debugging
+# Troubleshooting
 
 Log levels are controlled on a per-module basis, and by default all logging is disabled except for errors. Logging is controlled via the `RUST_LOG` environment variable. The value of this environment variable is a comma-separated list of logging directives.
 

docs/src/using-with-mapbox.md

@@ -1,8 +1,8 @@
 # Using with Mapbox
 
-[Mapbox GL JS](https://github.com/mapbox/mapbox-gl-js) is a JavaScript library for interactive, customizable vector maps on the web. Mapbox GL JS v1.x was open source, and it was forked as MapLibre (see [above](#using-with-maplibre)), so using Martin with Mapbox is similar to MapLibre. Mapbox GL JS can accept [MVT vector tiles](https://github.com/mapbox/vector-tile-spec) generated by Martin, and applies [a style](https://docs.mapbox.com/mapbox-gl-js/style-spec/) to them to draw a map using Web GL.
+[Mapbox GL JS](https://github.com/mapbox/mapbox-gl-js) is a JavaScript library for interactive, customizable vector maps on the web. Mapbox GL JS v1.x was open source, and it was forked as MapLibre, so using Martin with Mapbox is similar to MapLibre described [here](using-with-maplibre.md). Mapbox GL JS can accept [MVT vector tiles](https://github.com/mapbox/vector-tile-spec) generated by Martin, and applies [a style](https://docs.mapbox.com/mapbox-gl-js/style-spec/) to them to draw a map using Web GL.
 
-You can add a layer to the map and specify Martin TileJSON endpoint as a vector source URL. You should also specify a `source-layer` property. For [Table Sources](#table-sources) it is `{table_name}` by default.
+You can add a layer to the map and specify Martin TileJSON endpoint as a vector source URL. You should also specify a `source-layer` property. For [Table Sources](sources-pg-tables.md) it is `{table_name}` by default.
 
 ```js
 map.addLayer({

docs/src/using-with-maplibre.md

@@ -1,7 +1,8 @@
 # Using with MapLibre
+
 [MapLibre](https://maplibre.org/projects/maplibre-gl-js/) is an Open-source JavaScript library for showing maps on a website. MapLibre can accept [MVT vector tiles](https://github.com/mapbox/vector-tile-spec) generated by Martin, and applies [a style](https://maplibre.org/maplibre-gl-js-docs/style-spec/) to them to draw a map using Web GL.
 
-You can add a layer to the map and specify Martin [TileJSON](https://github.com/mapbox/tilejson-spec) endpoint as a vector source URL. You should also specify a `source-layer` property. For [Table Sources](#table-sources) it is `{table_name}` by default.
+You can add a layer to the map and specify Martin [TileJSON](https://github.com/mapbox/tilejson-spec) endpoint as a vector source URL. You should also specify a `source-layer` property. For [Table Sources](sources-pg-tables.md) it is `{table_name}` by default.
 
 
 ```js
@@ -35,7 +36,7 @@ map.addLayer({
 });
 ```
 
-You can also combine multiple sources into one source with [Composite Sources](#composite-sources). Each source in a composite source can be accessed with its `{source_name}` as a `source-layer` property.
+You can also combine multiple sources into one source with [Composite Sources](sources-composite.md). Each source in a composite source can be accessed with its `{source_name}` as a `source-layer` property.
 
 ```js
 map.addSource('points', {

docs/src/using.md

@@ -0,0 +1,49 @@
+# Martin Endpoints
+
+Martin data is available via the HTTP `GET` endpoints:
+
+| URL                                    | Description                                    |
+|----------------------------------------|------------------------------------------------|
+| `/`                                    | Status text, that will eventually show web UI  |
+| `/catalog`                             | [List of all sources](#catalog)                |
+| `/{sourceID}`                          | [Source TileJSON](#source-tilejson)            |
+| `/{sourceID}/{z}/{x}/{y}`              | Map Tiles                                      |
+| `/{source1},...,{sourceN}`             | [Composite Source TileJSON](#source-tilejson)  |
+| `/{source1},...,{sourceN}/{z}/{x}/{y}` | [Composite Source Tiles](sources-composite.md) |
+| `/health`                              | Martin server health check: returns 200 `OK`   |
+
+## Duplicate Source ID
+In case there is more than one source that has the same name, e.g. a PG function is available in two schemas/connections, or a table has more than one geometry columns, sources will be assigned unique IDs such as `/points`, `/points.1`, etc.
+
+## Catalog
+
+A list of all available sources is available via catalogue endpoint:
+
+```shell
+curl localhost:3000/catalog | jq
+```
+
+```yaml
+[
+  {
+    "id": "function_zxy_query",
+    "name": "public.function_zxy_query"
+  },
+  {
+    "id": "points1",
+    "name": "public.points1.geom"
+  },
+  ...
+]
+```
+
+## Source TileJSON
+
+All tile sources have a [TileJSON](https://github.com/mapbox/tilejson-spec) endpoint available at the `/{SourceID}`.
+
+For example, a `points` function or a table will be available as `/points`. Composite source combining `points` and `lines` sources will be available at `/points,lines` endpoint.
+
+```shell
+curl localhost:3000/points | jq
+curl localhost:3000/points,lines | jq
+```

justfile

@@ -97,11 +97,11 @@ bless: start clean-test
 
 # Build and open mdbook documentation
 mdbook:
-    if ! command -v mdbook &> /dev/null; then \
+    @if ! command -v mdbook &> /dev/null; then \
         echo "mdbook could not be found. Installing..." ;\
         cargo install mdbook ;\
     fi
-    mdbook build docs --open
+    mdbook serve docs --open
 
 # Build and open code documentation
 docs:
@@ -111,7 +111,7 @@ docs:
 coverage FORMAT='html':
     #!/usr/bin/env bash
     set -euo pipefail
-    if ! command -v grcov &> /dev/null; then \
+    @if ! command -v grcov &> /dev/null; then \
         echo "grcov could not be found. Installing..." ;\
         cargo install grcov ;\
     fi
@@ -190,7 +190,7 @@ git-pre-push: stop start
 
 # Update sqlite database schema. Install SQLX cli if not already installed.
 prepare-sqlite:
-    if ! command -v cargo-sqlx &> /dev/null; then \
+    @if ! command -v cargo-sqlx &> /dev/null; then \
         echo "SQLX could not be found. Installing..." ;\
         cargo install sqlx-cli --no-default-features --features sqlite,native-tls ;\
     fi