docs: revised developer guide documentation BM-1073 (#3347)

### Motivation

As a Basemaps developer I would like instructions to build Basemaps
locally so I can set up a development environment to contribute to
Basemaps code base.

### Modifications

I have added several documents to the developer guide section describing
how a user can build the Basemaps system and run the server package.

### Verification

I have run through the processes described in my documents. However, I
have tested them only from a Linux machine. The processes require only
Node.js, so the process should not be different for users on Windows
machines.

docs/README.md

@@ -2,7 +2,7 @@
 
 [LINZ Basemaps](https://basemaps.linz.govt.nz) is a collection of tools to create and serve vector and raster basemaps using open source and open standards. It is designed to be light weight, cost efficient and fast.
 
-Basemaps currently supports both [Imagery](#aerial--satellite-imagery) and [Vector data](#vector-data)
+Basemaps currently supports both [Imagery](#aerial--satellite-imagery-processing) and [Vector data](#vector-data)
 
 ## Background
 

docs/developer-guide/README.md

@@ -2,7 +2,7 @@
 
 Documentation of the Basemaps codebase for developers
 
-- How to build
+- [How to run `basemaps` locally](./run-basemaps-locally.md)
 - Contributing guidelines
 - TypeDoc API docs
 

docs/developer-guide/cli-methods/bundle-the-basemaps-config-file.md

@@ -0,0 +1,92 @@
+# Bundle the `basemaps` config file
+
+This guide explains how to generate the `basemaps` bundled config file using the **basemaps/cli** package.
+
+## Prerequisites
+
+### Imagery
+
+=== "Using LINZ's imagery"
+
+You'll need **AWS credentials** with permission to read files from the **LINZ AWS S3** bucket at `s3://linz-basemaps`. Such credentials are required to access LINZ's imagery when bundling the config file.
+
+## Get started
+
+Clone the [**linz/basemaps-config**][bm_config_repo] repository to your machine.
+
+=== "HTTPS"
+
+    ```bash
+    git clone https://github.com/linz/basemaps-config.git
+    ```
+
+=== "SSH"
+
+    ```bash
+    git clone [email protected]:linz/basemaps-config.git
+    ```
+
+=== "GitHub CLI"
+
+    ```bash
+    gh repo clone linz/basemaps-config
+    ```
+
+!!! abstract "Path"
+
+    This guide uses variables as shorthand to reference key directories and files. On your machine, note the following paths:
+
+    === "`BM_CONFIG_REPO`"
+
+        The path to the **basemaps-config** repository folder on your machine.
+
+        ```bash
+        $BM_CONFIG_REPO = {path_to}/basemaps-config
+        ```
+
+    === "`BM_CLI_BIN`"
+
+        The **basemaps/cli** package provides a **bundle** function we can use to generate a bundled config file.
+
+        The path to the **bin** folder of the **basemaps/cli** package.
+
+        ```bash
+        $BM_CLI_BIN = $BM_REPO/packages/cli/bin
+        ```
+
+## Run the `basemaps/cli` package
+
+### Command
+
+Use the following command to bundle the `basemaps` config file:
+
+```bash
+node $BM_CLI_BIN/bmc.js bundle \
+    --config $BM_CONFIG_REPO/config \
+    --output $BM_REPO/config/config.bundle.json \
+    --cache s3://linz-basemaps-staging/basemaps-config/cache/
+```
+
+### Parameters
+
+=== "`--config`"
+
+    Specifies the location of the config folder to use. This folder refers to that of which is within the `basemaps-config` repository.
+
+=== "`--output`"
+
+    Specifies where to save the bundled config file. You can specify a location of your choice. This guide specifies the `basemaps` repository for convenience.
+
+=== "`--cache`"
+
+    Specifies the location of the cache directory. This parameter is optional but recommended to reduce the time needed to construct the config file.
+
+<!-- internal links -->
+
+[running-basemaps-locally]: ../running-basemaps-locally.md
+[configuring-the-basemapsserver-package]: ../running-basemaps-locally.md#2-configuring-the-basemapsserver-package
+[path-to-json-config-file]: ../Server%20Methods/json-config-file.md
+
+<!-- external links -->
+
+[bm_config_repo]: https://github.com/linz/basemaps-config

docs/developer-guide/run-basemaps-locally.md

@@ -0,0 +1,105 @@
+# How to run `basemaps` locally
+
+This guide shows you how to set up and run a local instance of the **basemaps** system on your machine. This guide explains how to:
+
+- build the **basemaps** packages
+- configure and run the **basemaps/server** package:
+    - using LINZ's imagery
+    - using your own imagery
+
+!!! note
+
+    If you're planning to contribute to the **basemaps** repository, make sure you review the [**CONTRIBUTING**][contributing] document beforehand.
+
+## Prerequisites
+
+### NodeJS
+
+You'll need **[Node.js](https://nodejs.org)** version `18` or higher to build the **basemaps** packages.
+
+!!! tip
+
+    You can use tools like [**fnm**](https://github.com/Schniz/fnm) or [**n**](https://github.com/tj/n) to manage **Node.js** versions on your machine.
+
+### Imagery
+
+=== "Using LINZ's imagery"
+
+    You'll need **AWS credentials** with permission to read files from the **LINZ AWS S3** bucket at `s3://linz-basemaps`. Such credentials are needed to access or generate the config file required to run the **basemaps** system using LINZ's imagery.
+
+=== "Using your own imagery"
+
+    You'll need a **collection of GeoTIFF files** organised in any way you prefer. The collection must maintain a consistent resolution and spatial reference throughout. The **basemaps** system is only compatible with datasets with a uniform ground sampling distance and map projection.
+
+## Get started
+
+Clone the [**linz/basemaps**][bm_repo] repository to your machine.
+
+=== "HTTPS"
+
+    ```bash
+    git clone https://github.com/linz/basemaps.git
+    ```
+
+=== "SSH"
+
+    ```bash
+    git clone [email protected]:linz/basemaps.git
+    ```
+
+=== "GitHub CLI"
+
+    ```bash
+    gh repo clone linz/basemaps
+    ```
+
+!!! abstract "Path"
+
+    This guide uses variables as shorthand to reference key directories and files. On your machine, consider the following path:
+
+    === "`BM_REPO`"
+
+        The path to the **basemaps** repository folder on your machine.
+
+        ```bash
+        $BM_REPO = {path_to}/basemaps
+        ```
+
+## Build the `basemaps` packages
+
+In a terminal, navigate to `BM_REPO` and run the following commands:
+
+```bash
+# Install the Node.js dependencies for the system
+npm install
+
+# Generate the <package_name>/build for each package
+npm run build
+
+# Run the unit tests for each package
+npm run test
+```
+
+## Configure the `basemaps/server` package
+
+There are two main ways you can configure and run the **basemaps/server** package:
+
+=== "Using a bundled config file"
+
+    [Serve `basemaps` using a bundled config file][bundled-config-file]
+
+=== "Using a collection of GeoTIFF files"
+
+    [Serve `basemaps` using a collection of GeoTIFF files][collection-of-geotiff-files]
+
+<!-- internal links -->
+
+[bundled-config-file]: ./server-methods/serve-basemaps-with-bundled-config-file.md
+[collection-of-geotiff-files]: ./server-methods/serve-basemaps-with-collection-of-geotiff-files.md
+
+<!-- external links -->
+
+[bm_repo]: https://github.com/linz/basemaps
+[configuration]: https://github.com/linz/basemaps/blob/master/docs/configuration.md
+[contributing]: https://github.com/linz/basemaps/blob/master/CONTRIBUTING.md
+[stac]: https://github.com/radiantearth/stac-spec/blob/master/overview.md

docs/developer-guide/server-methods/serve-basemaps-with-bundled-config-file.md

@@ -0,0 +1,75 @@
+# Serve `basemaps` using a bundled config file
+
+This guide shows you how to configure and run the **basemaps/server** package using a bundled config file. The config file specifies metadata regarding which imagery collections the package can serve from the **LINZ AWS S3** bucket.
+
+## Configure the `basemaps/server` package
+
+The **basemaps/server** package requires a config file to serve the **basemaps** system.
+
+You have two options. The first is to use the pre-generated config file stored in the **LINZ AWS S3** bucket. The second is to generate the config file yourself using the **basemaps/cli** package.
+
+=== "Using the pre-generated config file"
+
+    !!! abstract "Path"
+
+        To use the exisiting config file stored in the **LINZ AWS S3** bucket, note of the following path:
+
+        === "`CONFIG_FILE`"
+
+            The absolute path to the latest config file stored in the **LINZ AWS S3** bucket.
+            
+            ```bash
+            $CONFIG_FILE = s3://linz-basemaps/config/config-latest.json.gz
+            ```
+
+=== "Generating the config file yourself"
+
+    To generate the config file yourself, follow the [**Bundle the `basemaps` config file**][bundle-the-basemaps-config-file] guide. Then, return to this section.
+
+    !!! abstract "Path"
+
+        Once you have generated the config file, make a note of the file's location:
+
+        === "`CONFIG_FILE`"
+
+            The path to the generated config file on your machine.
+            
+            ```bash
+            $CONFIG_FILE = {path_to}/config.bundle.json
+            ```
+
+## Run the `basemaps/server` package
+
+At this stage, you should have a path to a config file. Either, to that which you are sourcing from the **LINZ AWS S3** bucket, or, have generated using the **basemaps/cli** package.
+
+!!! abstract "Path"
+
+    The **basemaps/server** package provides a default function to serve the **basemaps** system. Take note of the following path:
+
+    === "`BM_SERVER_BIN`"
+
+        The path to the **bin** folder of the **basemaps/server** package.
+            
+        ```bash
+        $BM_SERVER_BIN = $BM_REPO/packages/server/bin
+        ```
+
+### Command
+
+Use the following command to run the **basemaps** system:
+
+```bash
+node $BM_SERVER_BIN/basemaps-server.cjs --config $CONFIG_FILE
+```
+
+### Parameters
+
+=== "`--config`"
+
+    Specifies the location of the bundled config file to use.
+
+<!-- internal links -->
+
+[running-basemaps-locally]: ../running-basemaps-locally.md
+[configuring-the-basemapsserver-package]: ../running-basemaps-locally.md#2-configuring-the-basemapsserver-package
+[bundle-the-basemaps-config-file]: ../cli-methods/bundle-the-basemaps-config-file.md

docs/developer-guide/server-methods/serve-basemaps-with-collection-of-geotiff-files.md

@@ -0,0 +1,46 @@
+# Serve `basemaps` using a collection of GeoTIFF files
+
+This guide shows you how to configure and run the **basemaps/server** package using a collection of GeoTIFF files.
+
+## Configure the `basemaps/server` package
+
+The **basemaps/server** package requires a collection of GeoTIFF files from which it can serve the **basemaps** system.
+
+!!! abstract "Path"
+
+    Make a note of the following path:
+
+    === "`IMAGERY_DIR`"
+
+        The path to the root folder of your GeoTIFF file collection.
+            
+        ```bash
+        $IMAGERY_DIR = {path_to_imagery_directory}
+        ```
+
+## Run the `basemaps/server` package
+
+!!! abstract "Path"
+
+    The **basemaps/server** package provides a default function to serve the **basemaps** system. Note the following path:
+
+    === "`BM_SERVER_BIN`"
+
+        The path to the **bin** folder of the **basemaps/server** package.
+            
+        ```bash
+        $BM_SERVER_BIN = $BM_REPO/packages/server/bin
+        ```
+
+### Command
+
+Use the following command to run the **Basemaps** system:
+
+```bash
+node $BM_SERVER_BIN/basemaps-server.cjs $IMAGERY_DIR
+```
+
+<!-- internal links -->
+
+[running-basemaps-locally]: ../running-basemaps-locally.md
+[configuring-the-basemapsserver-package]: ../running-basemaps-locally.md#2-configuring-the-basemapsserver-package

mkdocs.yml

@@ -68,6 +68,12 @@ markdown_extensions:
   # https://facelessuser.github.io/pymdown-extensions/extensions/details/
   - pymdownx.details
 
+  # Allows grouping content snippets under labelled tabs
+  #
+  # https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
+  - pymdownx.tabbed:
+      alternate_style: true
+
 # Load google analytics from the $GOOGLE_ANALYTICS environment var
 extra:
   analytics: