docs: revise developer guide documentation BM-1081

docs/developer-guide/cli-methods/bundle-the-basemaps-assets-archive.md

@@ -0,0 +1,158 @@
+# Bundle the `basemaps` assets archive
+
+This guide explains how to generate the `basemaps` bundled assets archive using the **basemaps/cli** package.
+
+## 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 "Paths"
+
+    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_BUILD`"
+
+        The **basemaps/cli** package provides a **bundle-assets** function we can use to generate a bundled assets archive.
+
+        The path to the **build** folder of the **basemaps/cli** package.
+
+        ```bash
+        $BM_CLI_BUILD = $BM_REPO/packages/cli/build/cli
+        ```
+
+    === "`BM_SPRITES_BIN`"
+
+        The **basemaps/sprites** package provides a default function we can use to generate sprite sheets from a collection of sprite images.
+
+        The path to the **bin** folder of the **basemaps/sprites** package.
+
+        ```bash
+        $BM_SPRITES_BIN = $BM_REPO/packages/sprites/bin
+        ```
+
+## Generate the `basemaps` assets
+
+### 1. Create local directory
+
+To prepare for bundling the `basemaps` assets archive, create a local directory on your machine with the following subdirectory structure:
+
+```md
+- assets
+  - fonts
+  - sprites
+```
+
+You can specify a location and directory name of your choice.
+
+!!! abstract "Path"
+
+    On your machine, consider the following path:
+
+    === "`ASSETS_DIR`"
+
+        The path to the created directory on your machine.
+
+        ```bash
+        $ASSETS_DIR = {path_to_directory}
+        ```
+
+### 2. Convert fonts into `.pbf` (protobuf-encoded glyphs) files
+
+To generate the `basemaps` `.pbf` files, follow the instructions described in this [README.md][fonts_readme] file. Alternatively, there is a [repository][pbf_fonts_repo] containing various fonts that have already been converted into the `.pbf` format.
+
+Move the generated and/or downloaded collections of `.pbf` files **into** the following directory:
+
+```
+$ASSETS_DIR/assets/fonts
+```
+
+The contents of your `$ASSETS_DIR/assets/fonts` directory should look similar to the following:
+
+```md
+- $ASSETS_DIR/assets/fonts
+  - Noto Sans Bold
+    - 0-255.pbf
+    - ...
+  - Open Sans Bold
+    - 0-255.pbf
+    - ...
+```
+
+### 3. Convert sprite files into sprite sheets
+
+Use the following command to generate the `basemaps` sprite sheets from the collection of topographic sprite files:
+
+```bash
+node $BM_SPRITES_BIN/basemaps-sprites.mjs \
+$BM_CONFIG_REPO/config/sprites/topographic
+```
+
+The above command will output the resulting sprite sheets to the location from which you executed the command. Move the outputted files **into** the following directory:
+
+```md
+$ASSETS_DIR/assets/sprites
+```
+
+The contents of your `$ASSETS_DIR/assets/sprites` directory should look similar to the following:
+
+```md
+- $ASSETS_DIR/assets/sprites
+  - topographic.json
+  - topographic.png
+  - [email protected]
+  - [email protected]
+```
+
+## Run the `basemaps/cli` package
+
+### Command
+
+Use the following command to bundle the `basemaps` assets archive:
+
+```bash
+node $BM_CLI_BUILD/bin.js bundle-assets \
+    --assets $ASSETS_DIR \
+    --output assets.bundle.tar.co \
+```
+
+### Parameters
+
+=== "`--assets`"
+
+    Specifies the location of the assets folder to use. This folder refers to that which contains the `.pbf` files and sprite sheets on your local machine.
+
+=== "`--output`"
+
+    Specifies where to save the bundled assets archive, relative to the location from which you execute the command. You can specify a location and filename of your choice.
+
+<!-- external links -->
+
+[bm_config_repo]: https://github.com/linz/basemaps-config
+[fonts_readme]: https://github.com/linz/basemaps-config/tree/master/config/fonts
+[pbf_fonts_repo]: https://github.com/korywka/fonts.pbf

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

@@ -32,10 +32,10 @@ Clone the [**linz/basemaps-config**][bm_config_repo] repository to your machine.
     gh repo clone linz/basemaps-config
     ```
 
-!!! abstract "Path"
+!!! abstract "Paths"
 
     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.
@@ -44,14 +44,14 @@ Clone the [**linz/basemaps-config**][bm_config_repo] repository to your machine.
         $BM_CONFIG_REPO = {path_to}/basemaps-config
         ```
 
-    === "`BM_CLI_BIN`"
+    === "`BM_CLI_BUILD`"
 
         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.
+        The path to the **build** folder of the **basemaps/cli** package.
 
         ```bash
-        $BM_CLI_BIN = $BM_REPO/packages/cli/bin
+        $BM_CLI_BUILD = $BM_REPO/packages/cli/build/cli
         ```
 
 ## Run the `basemaps/cli` package
@@ -61,9 +61,9 @@ Clone the [**linz/basemaps-config**][bm_config_repo] repository to your machine.
 Use the following command to bundle the `basemaps` config file:
 
 ```bash
-node $BM_CLI_BIN/bmc.js bundle \
+node $BM_CLI_BUILD/bin.js bundle \
     --config $BM_CONFIG_REPO/config \
-    --output $BM_REPO/config/config.bundle.json \
+    --output config.bundle.json \
     --cache s3://linz-basemaps-staging/basemaps-config/cache/
 ```
 
@@ -75,18 +75,12 @@ node $BM_CLI_BIN/bmc.js bundle \
 
 === "`--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.
+    Specifies where to save the bundled config file, relative to the location from which you execute the command. You can specify a location and filename of your choice.
 
 === "`--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
+[bm_config_repo]: https://github.com/linz/basemaps-config

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

@@ -80,6 +80,15 @@ npm run build
 npm run test
 ```
 
+!!! tip
+
+    You can build the `basemaps` packages in [watch mode][tsc_watch] so that they recompile anytime you modify the source code. In a terminal, navigate to `BM_REPO` and run the following command:
+
+    ```bash
+    # Generate the <package_name>/build for each package (watch mode)
+    npm run build -- --watch
+    ```
+
 ## Configure the `basemaps/server` package
 
 There are two main ways you can configure and run the **basemaps/server** package:
@@ -103,3 +112,4 @@ There are two main ways you can configure and run the **basemaps/server** packag
 [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
+[tsc_watch]: https://www.typescriptlang.org/docs/handbook/project-references.html#tsc--b-commandline