MIM-2768 Migrate the docs to Zensical

.circleci/template.yml

@@ -490,7 +490,7 @@ jobs:
       - add_ssh_keys
       - run:
           name: Install tools for building docs
-          command: tools/install-mkdocs.sh
+          command: tools/install-docs-tools.sh
       - run:
           name: Build the docs
           command: tools/build-docs.sh
@@ -523,7 +523,6 @@ jobs:
                 command: |
                   ssh-keyscan github.com >> ~/.ssh/known_hosts
                   git fetch git@github.com:esl/MongooseDocs.git gh-pages:gh-pages
-                  pip3 install mike
                   mike deploy $DOCS_TAG --remote git@github.com:esl/MongooseDocs.git --branch gh-pages --push
 
   build_in_docker:

CONTRIBUTING.md

@@ -22,6 +22,7 @@ Write type specifications and function signatures because they're remarkably hel
 Place technical documentaion in the directory `doc`.
 Find or create a suitable place for your material in terms of which page and section you write it in.
 Where documentation is placed is paramount, otherwise regardless of its quality, it will be harder to find it if at all.
+To see your changes rendered, build the site locally as [described in the docs](https://esl.github.io/MongooseDocs/latest/developers-guide/Building-the-documentation/).
 
 What makes a good comment?
 Write about why something is done a certain way.

Makefile

@@ -1,4 +1,4 @@
-.PHONY: rel docs
+.PHONY: rel docs docs-serve
 
 # GNU Make is required. Use gmake on BSD systems.
 
@@ -85,6 +85,11 @@ docs: xeplist
 	## if build-docs.sh fails, mim_docs container remains running, so we can exec into it and debug ##
 	##################################################################################################
 	docker run --rm -d -v "$(PWD):/mim" -w /mim --name mim_docs cimg/python:3.11.5-node sleep infinity
-	docker exec mim_docs tools/install-mkdocs.sh &>/dev/null
+	docker exec mim_docs tools/install-docs-tools.sh &>/dev/null
 	docker exec mim_docs tools/build-docs.sh  &>/dev/null
 	docker stop mim_docs
+
+## Serve the docs locally with live reload, without going through Docker.
+## Requires `pip3 install zensical`.
+docs-serve: xeplist
+	zensical serve

doc/css/custom.css

@@ -7,3 +7,8 @@ img#mim-readme-logo {
   --md-primary-fg-color: #459bb6;
   --md-accent-fg-color: #0554b8;
 }
+
+/* dark theme */
+[data-md-color-scheme="slate"] {
+  --md-accent-fg-color: #7ab5ff;
+}

doc/developers-guide/Building-the-documentation.md

@@ -0,0 +1,34 @@
+# Building the documentation
+
+These docs live in `doc/` and are built with [Zensical](https://zensical.org/), configured by `mkdocs.yml` in the repository root - navigation, theme and Markdown extensions all come from that file.
+
+## Preview while you write
+
+```sh
+pip3 install zensical
+zensical serve
+```
+
+The site shows up at [http://localhost:8000](http://localhost:8000) and reloads whenever you save a file.
+`make docs-serve` runs the same thing, but regenerates the supported XEP lists first with the [xep-tool](xep_tool.md), which reads compiled modules from `_build/prod/lib` - so use it only if you have built the release.
+
+The GraphQL API reference pages will look empty: they are generated by the two `npx spectaql` commands in `tools/build-docs.sh`.
+
+## Before you push
+
+```sh
+zensical build --strict
+```
+
+Strict mode turns warnings into errors, most usefully links to pages and anchors that do not exist.
+CI runs the same command and the build takes a few seconds, so there is no reason to find out on CI instead.
+If the results look stale, add `-c` to drop the build cache.
+
+`make docs` is the whole CI build - XEP lists, GraphQL pages and site - inside a Docker container, so it needs no Python or Node on your machine.
+When it fails, the `mim_docs` container is deliberately left running for you to `docker exec -it mim_docs bash` into.
+
+## Writing
+
+Include another file with `--8<-- "path/to/file.md"`, relative to `doc/`.
+Diagrams go in a ` ```mermaid ` fence.
+Content tabs, admonitions and highlighted code blocks with line numbers are available too.

doc/listeners/listen-http.md

@@ -137,7 +137,7 @@ The default value is 1 hour.
 
 Requires no additional options other than the [common handler options](#common-handler-options) in the listener section.
 In order to collect useful metrics, a `[prometheus]` section has to be added in [the instrumentation section](../configuration/instrumentation.md#).
-The default configuration available with MongooseIM is shown in [Example 7](#example-7-prometheus) below.
+The default configuration available with MongooseIM is shown in [Example 5](#example-5-prometheus) below.
 
 ## Transport options
 

doc/migrations/5.0.0_5.1.0.md

@@ -9,7 +9,7 @@ The options `tls.verify_peer` and `tls.verify_mode` are replaced with just [`tls
 * `verify_peer = false` (the old default for C2S and HTTP listeners) should be replaced with `verify_mode = "none"`.
 * `verify_peer = true` should be replaced with `verify_mode = "peer"` or just removed, as this is the new default.
 
-There is a new, simplified configuration format for `mongoose_client_api`. You need to change the `listen` section unless you have disabled the client API in your configuration file. Consult the [option description](../listeners/listen-http.md#handler-types-rest-api-client-mongoose_client_api) and the [example configuration](../listeners/listen-http.md#example-6-client-rest-api) for details.
+There is a new, simplified configuration format for `mongoose_client_api`. You need to change the `listen` section unless you have disabled the client API in your configuration file. Consult the [option description](../listeners/listen-http.md) and the [example configuration](../listeners/listen-http.md) for details.
 
 ### Section `acl`
 

doc/migrations/5.1.0_6.0.0.md

@@ -1,7 +1,7 @@
 ## Module configuration
 
 * The `mod_mam_meta` module is now named `mod_mam` for simplicity, so if you are using this module, you need to update the module name in `mongooseim.toml`.
-* `mod_commands`, `mod_inbox_commands`, `mod_muc_commands` and `mod_muc_light_commands` are removed. Their functionality is now fully covered by [`mongoose_admin_api`](../listeners/listen-http.md/#handler-types-rest-api-admin-mongoose_admin_api). You need to delete these modules from `mongooseim.toml`.
+* `mod_commands`, `mod_inbox_commands`, `mod_muc_commands` and `mod_muc_light_commands` are removed. Their functionality is now fully covered by [`mongoose_admin_api`](../listeners/listen-http.md). You need to delete these modules from `mongooseim.toml`.
 
 ## Metrics
 
@@ -11,8 +11,8 @@ The `mod_mam` backend module is now named `mod_mam_pm` for consistency with `mod
 
 The whole REST API has been unified and simplified. There are now only two REST API handlers that you can configure in the `listen` section of `mongooseim.toml`:
 
-- [`mongoose_admin_api`](../listeners/listen-http.md/#handler-types-rest-api-admin-mongoose_admin_api) handles the administrative API,
-- [`mongoose_client_api`](../listeners/listen-http.md/#handler-types-rest-api-client-mongoose_client_api) handles the client-facing API.
+- [`mongoose_admin_api`](../listeners/listen-http.md) handles the administrative API,
+- [`mongoose_client_api`](../listeners/listen-http.md) handles the client-facing API.
 
 You need to remove the references to the obsolete handlers (`mongoose_api_client`, `mongoose_api_admin`, `mongoose_api`, `mongoose_domain_handler`) from your configuration file.
 

doc/migrations/6.5.0_6.6.0.md

@@ -4,7 +4,7 @@ The following features are removed or deprecated.
 
 ### MS SQL and ODBC are no longer supported
 
-The Microsoft SQL Server database is no longer supported, and you cannot set the [RDBMS driver](../configuration/outgoing-connections.md/#outgoing_poolsrdbmsconnectiondriver) to `odbc` anymore.
+The Microsoft SQL Server database is no longer supported, and you cannot set the [RDBMS driver](../configuration/outgoing-connections.md#outgoing_poolsrdbmsconnectiondriver) to `odbc` anymore.
 In case you used this database, you need to migrate to another supported RDBMS, e.g. MySQL, MariaDB, PostgreSQL or CockroachDB.
 
 ### Removal of admin REST API