docs: add more meat to the development section

docs/README.md

@@ -0,0 +1,31 @@
+# Martins documentation
+
+The documentation of `maplibre/martin` is available at <https://maplibre.org/martin>.
+
+To build/develop this documentation locally, you can install `mdbook` and `mdbook-linkcheck`.
+
+```bash
+cargo install mdbook
+```
+
+## Development
+
+You can simply edit the markdown files in the `src` directory and run the following command (from the project root directory) to preview the changes:
+
+```bash
+mdbook watch --open docs
+```
+
+Next to showing you how the docs will look, this also runs a link checker to ensure that all links are valid.
+
+> [!TIP]
+> Make sure that all pages are linked from [`src/SUMMARY.md`](src/SUMMARY.md).
+> **Only** pages linked will be rendered.
+> See the [mdbook documentation](https://rust-lang.github.io/mdBook/) for more information.
+
+> [!NOTE]
+> Files may only be added, not renamed.
+> If you want to rename a file, make sure to [add a redirect to the new file in `output.html.redirect`](https://rust-lang.github.io/mdBook/format/configuration/renderers.html#outputhtmlredirect).
+> Renaming files would otherwise break existing, external links for example on stackoverflow or github-discussions.
+>
+> Removing is bad for the same reasons and will be handled on a case-by-case basis.

docs/src/development.md

@@ -1,33 +1,108 @@
 # Development
 
-Clone Martin, setting remote name to `upstream`. This way `main` branch will be updated automatically with the latest
-changes from the upstream repo.
+## Git setup
 
-```bash, ignore
-git clone https://github.com/maplibre/martin.git -o upstream
+The recommended setup for both core and casual contributors is to **always** create a fork
+of the primary repo under their own account. The local repo should have two remotes: `upstream` pointing to the primary `maplibre/martin` repo, and `origin` pointing to the user's own fork. The `main` branch should track `upstream/main`, but all new work will be pushed to `origin` and PRs will be created from there.
+
+<details><summary>Rationale for this setup (click to expand)</summary>
+
+<small>This rationale was copied from [a post](https://gist.github.com/nyurik/4e299ad832fd2dd43d2b27191ed3ec30) by Yuri</small>
+
+Open source contribution is both a technical and a social phenomenon.
+Any FOSS project naturally has a "caste system" - a group
+of contributors with extensive rights vs everyone else. Some of this separation
+is necessary - core contributors have deeper knowledge of the code, share vision,
+and trust each other.
+
+Core contributors have one more right that others do not -- they can create repository branches.
+Thus, they can contribute "locally" - by pushing proposed changes to the primary repository's work branches,
+and create "local" pull requests inside the same repo.  This is different from others,
+who can contribute only from their own forks.
+
+There is little difference between creating pull requests from one's own fork and from the primary repo,
+and there are a few reasons why core contributors should **never** do it from the primary repo:
+
+* it ensures that casual contributors always run the same CI as core contributors. If contribution process breaks, it will affect everyone, and will get fixed faster.
+* it puts everyone on the same leveled playing field, reducing the "caste system" effect, making the project feel more welcoming to new contributors
+* it ensures that the primary repo only has maintained branches (e.g. `main` and `v1.x`),
+  not a bunch of PR branches whose ownership and work status is unclear to everyone
+
+In the martin repository, we follow this and have a branch protection rule that prevents core contributors from creating pull requests from the primary repo.
+
+</details>
+
+```bash
+# clone the primary fork to your local machine, naming the remote "upstream"
+# make sure to replace the URL with the correct one
+git clone -o upstream https://github.com/maplibre/martin.git
 cd martin
+
+# add your own fork as a remote, naming it "origin"
+git remote add origin https://github.com/nyurik/martin.git
 ```
 
-Fork Martin repo into your own GitHub account, and add your fork as a remote
+For further setup instructions for IDEs, please see the [Getting Involved](getting-involved.md) step after you have installed the necessary tools below.
+<details><summary>If you have already cloned the repo locally, use this guide to update your setup (click to expand)</summary>
 
-```bash, ignore
-git remote add origin  _URL_OF_YOUR_FORK_
+If you already cloned the repo locally, you can update it to use the new setup. This assumes you have a local clone of the repo, the remote name is `origin`, and you have already forked the repo on GitHub.
+
+```bash
+# Getting a quick glance about your remotes: git remote -v
+git remote -v
+# Rename the existing remote to "upstream". Your "main" branch will now track "upstream/main"
+git remote rename origin upstream
+
+# Add your own fork as a remote, naming it "origin" (adjust the URL)
+git remote add origin https://github.com/nyurik/martin.git
 ```
 
-Install [docker](https://docs.docker.com/get-docker/) and [docker-compose](https://docs.docker.com/compose/)
+</details>
 
-```bash, ignore
-# Ubuntu-based distros have an older version that might also work:
-sudo apt install -y  docker.io docker-compose
+### Contributing New Code
+
+```bash
+# switch to main branch (tracking upstream/main), and pull the latest changes
+git switch main
+git fetch upstream
+
+# create a new branch for your work
+git switch -c my-new-feature
+
+# edit files, and commit changes
+# '-a' will add all modified files
+# `-m` allows you to add a short commit message
+git commit -a -m "My new feature"
+
+# push the changes to your own fork
+# '-u' will track your local branch with the remote
+git push -u origin my-new-feature
+
+# Click the link shown by `git push` in the terminal to create a pull request
+# from your fork using the GitHub web interface
 ```
 
+## Installed tools and libraries
+
 Install a few required libs and tools:
 
 ```bash, ignore
 # For Ubuntu-based distros
-sudo apt install -y  build-essential pkg-config jq file gdal-bin
+sudo apt update
+sudo apt install -y build-essential pkg-config jq file gdal-bin
+```
+
+### docker
+
+Install [docker](https://docs.docker.com/get-docker/) and [docker-compose](https://docs.docker.com/compose/)
+
+```bash, ignore
+# Ubuntu-based distros have an older version that might also work:
+sudo apt install -y  docker.io docker-compose
 ```
 
+### just
+
 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:
 

docs/src/martin-as-a-library.md

@@ -2,8 +2,16 @@
 
 Martin can be used as a standalone server, or as a library in your own Rust application. When used as a library, you can use the following features:
 
-* **postgres** - enable PostgreSQL/PostGIS tile sources
-* **pmtiles** - enable PMTile tile sources
-* **mbtiles** - enable MBTile tile sources
-* **fonts** - enable font sources
-* **sprites** - enable sprite sources
+* `webui` - enable web UI
+* tile sources
+  * `mbtiles` - enable MBTile tile sources
+  * `pmtiles` - enable PMTile tile sources
+  * `postgres` - enable PostgreSQL/PostGIS tile sources
+* supporting resources
+  * `fonts` - enable font sources
+  * `sprites` - enable sprite sources
+  * `styles` - enable style sources
+* `lambda` - add specialised support for running in serverless functions
+
+If you are missing a part of Martin functionality in the [public `martin` API](https://docs.rs/martin), we would love to hear from you.
+Please open an issue on our GitHub repository or directly open a pull request.