docs(cache): update the docs with our new cache capabilities (#2311)

Only to be merged close to release to prevent confusion

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: CommanderStorm

docs/src/config-file.md

@@ -37,8 +37,28 @@ base_path: /tiles
 # Number of web server workers
 worker_processes: 8
 
-# Amount of memory (in MB) to use for caching tiles [default: 512, 0 to disable]
-cache_size_mb: 1024
+# Amount of memory (in MB) to use for caching [default: 512, 0 to disable]
+#
+# This is the total amount of cache we use.
+# By default, this is split up between:
+# - Tiles 50% -> 256 MB
+# - Pmtiles' directories 25% -> 128 MB
+# - Fonts 12.5% -> 64 MB
+# - Sprites 12.5% -> 64 MB
+#
+# How the cache works internally is unstable and may change to improve performance/efficiency.
+# For example, we may change the split between sources to improve efficiency.
+#
+# Specify each cache size individually for finer cache size control:
+# - Tiles: `tile_cache_size_mb`
+# - Pmtiles: `pmtiles.directory_cache_size_mb`
+# - Fonts: `fonts.cache_size_mb`
+# - Sprites: `sprites.cache_size_mb`
+cache_size_mb: 512
+
+# Allows overriding the size of the tile cache.
+# Defaults to `cache_size_mb` / 2
+tile_cache_size_mb: 256
 
 # Which compression should be used if the
 # - client accepts multiple compression formats, and
@@ -231,6 +251,16 @@ postgres:
 
 # Publish PMTiles files from local disk or proxy to a web server
 pmtiles:
+  # Size of the directory cache (in MB).
+  # Defaults to cache_size_mb / 4
+  #
+  # Note:
+  # Tile and directory caching are complementary.
+  # For good performance, you want
+  # - directory caching (to not resolve the directory on each request) and
+  # - tile caching (for high access tiles)
+  directory_cache_size_mb: 128
+
   # You can pass options for pmtiles files located on remote storages here.
   #
   # The avaliable options are documented here:
@@ -282,6 +312,10 @@ cog:
 
 # Sprite configuration
 sprites:
+  # Size of the sprite cache (in MB).
+  # Defaults to cache_size_mb / 8
+  cache_size_mb: 64
+
   paths:
     # all SVG files in this dir will be published as a "my_images" sprite source
     - /path/to/my_images
@@ -291,6 +325,10 @@ sprites:
 
 # Font configuration
 fonts:
+  # Size of the sprite cache (in MB).
+  # Defaults to cache_size_mb / 4
+  cache_size_mb: 64
+
   # A list of *.otf, *.ttf, and *.ttc font files and dirs to search recursively.
   - /path/to/font/file.ttf
   - /path/to/font_dir

docs/src/run-with-nginx.md

@@ -1,6 +1,7 @@
 ## Using with NGINX
 
-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.
+You can run Martin behind NGINX proxy, so you can cache frequently accessed tiles with custom logic.
+Here is an example `docker-compose.yml` file that runs Martin with NGINX and PostgreSQL.
 
 ```yml
 version: '3'

docs/src/sources-cog-files.md

@@ -39,7 +39,7 @@ listen_addresses: '0.0.0.0:3000'
 # Number of web server workers
 worker_processes: 8
 
-# Amount of memory (in MB) to use for caching tiles [default: 512, 0 to disable]
+# Amount of memory (in MB) to use for caching [default: 512, 0 to disable]
 cache_size_mb: 8
 
 # Database configuration. This can also be a list of PG configs.

docs/src/sources-fonts.md

@@ -2,7 +2,7 @@
 
 Martin can serve glyph ranges from `otf`, `ttf`, and `ttc` fonts as needed by MapLibre text rendering. Martin will
 generate them dynamically on the fly.
-The glyph range generation is not yet cached, and may require external reverse proxy or CDN for faster operation.
+The glyph range generation is cached and the size of this cache can be configured via `fonts.cache_size_mb` in the config file.
 
 ## API
 

docs/src/sources-sprites.md

@@ -5,8 +5,7 @@ The SVG filenames without extension will be used as the sprites' image IDs (reme
 The images are searched recursively in the given directory, so subdirectory names will be used as prefixes for the image IDs.
 For example `icons/bicycle.svg` will be available as `icons/bicycle` sprite image.
 
-The sprite generation is not yet cached, and may require external reverse proxy or CDN for faster operation.
-If you would like to improve this, please drop us a pull request.
+The spritesheet generation is cached and the size of this cache can be configured via `sprites.cache_size_mb` in the config file.
 
 ### API