gh-pages deployment with material theme

.circleci/config.yml

@@ -155,7 +155,6 @@ orbs:
                   tools/circleci-prepare-log-dir.sh
                   if [ -n "${AWS_SECRET_ACCESS_KEY}" ]; then tools/circleci-upload-to-s3.sh; fi
 
-
       package:
         parallelism: 1
         machine:
@@ -179,6 +178,7 @@ orbs:
               name: Build package
               command: |
                 KEEP_COVER_RUNNING=1 ./tools/travis-test.sh -p pkg -s false
+
       big_tests:
         parallelism: 1
         machine:
@@ -261,6 +261,7 @@ orbs:
               command: |
                   tools/circleci-prepare-log-dir.sh
                   if [ -n "${AWS_SECRET_ACCESS_KEY}" ]; then tools/circleci-upload-to-s3.sh; fi
+
       docker_image:
         parallelism: 1
         machine:
@@ -287,6 +288,44 @@ orbs:
               name: Execute Docker image build and upload
               command: tools/circle-build-and-push-docker.sh
 
+jobs:
+  docs_build_deploy:
+    parallelism: 1
+    docker:
+      - image: cimg/python:3.9.0
+    working_directory: ~/app
+    steps:
+      - checkout
+      - run:
+          name: Test that docs build
+          command: |
+            pip3 install mkdocs
+            pip3 install mkdocs-material
+            mkdocs build --strict
+      - when:
+          condition:
+            or:
+              - equal: [ master, << pipeline.git.branch >> ]
+              - << pipeline.git.tag >>
+          steps:
+            - add_ssh_keys
+            - run:
+                name: Generate image tag
+                command: |
+                  set -x
+                  if [ -n "$CIRCLE_TAG" ]; then
+                      DOCS_TAG="$CIRCLE_TAG"
+                  elif [ "$CIRCLE_BRANCH" == "master" ]; then
+                      DOCS_TAG="latest"
+                  else
+                      DOCS_TAG=`echo $CIRCLE_BRANCH | sed 's,/,_,g'`
+                  fi
+            - run:
+                name: Build latest
+                command: |
+                  pip3 install mike
+                  mike deploy $DOCS_TAG --remote git@github.com:esl/MongooseDocs.git --branch main --push --force
+
 filters: &all_tags
   tags:
     only: /^\d+\.\d+\.\d+([a-z0-9\-\+])*/
@@ -457,3 +496,8 @@ workflows:
             - small_tests_21_3
             - small_tests_23
           filters: *all_tags
+      # ============= DOCUMENTATION =============
+      - docs_build_deploy:
+          name: build_and_deploy_docs
+          context: mongooseim-org
+          filters: *all_tags

README.md

@@ -1,16 +1,15 @@
 # MongooseIM platform
 
 [![Build Status](https://travis-ci.org/esl/MongooseIM.svg?branch=master)](https://travis-ci.org/esl/MongooseIM)
-[![Documentation Status](https://readthedocs.org/projects/mongooseim/badge/?version=latest)](https://mongooseim.readthedocs.org/en/latest/?badge=latest)
 [![codecov](https://codecov.io/gh/esl/MongooseIM/branch/master/graph/badge.svg)](https://codecov.io/gh/esl/MongooseIM)
 [![GitHub release](https://img.shields.io/github/release/esl/MongooseIM.svg)](https://github.com/esl/MongooseIM/releases)
 
 
-* [Getting started](https://mongooseim.readthedocs.io/en/latest/user-guide/Getting-started/)
-* [Developer's guide](https://mongooseim.readthedocs.io/en/latest/developers-guide/Testing-MongooseIM/)
+* [Getting started](https://esl.github.io/MongooseDocs/latest/user-guide/Getting-started/)
+* [Developer's guide](https://esl.github.io/MongooseDocs/latest/developers-guide/Testing-MongooseIM/)
 * [Packages](https://www.erlang-solutions.com/resources/download.html)
 * Product page: [https://www.erlang-solutions.com/products/mongooseim.html](https://www.erlang-solutions.com/products/mongooseim.html)
-* Documentation: [https://mongooseim.readthedocs.org/](https://mongooseim.readthedocs.org/)
+* Documentation: [https://esl.github.io/MongooseDocs/](https://esl.github.io/MongooseDocs/)
 
 ## Get to know MongooseIM
 MongooseIM is a robust and efficient chat (or instant messaging) platform aimed at large installations.
@@ -36,7 +35,7 @@ It is brought to you by [Erlang Solutions](https://www.erlang-solutions.com/).
 
 * Home: [http://github.com/esl/MongooseIM](http://github.com/esl/MongooseIM)
 * Product page: [https://www.erlang-solutions.com/products/mongooseim.html](https://www.erlang-solutions.com/products/mongooseim.html)
-* Documentation: [https://mongooseim.readthedocs.org/](https://mongooseim.readthedocs.org/)
+* Documentation: [https://esl.github.io/MongooseDocs/](https://esl.github.io/MongooseDocs/)
 
 ## Download packages
 
@@ -58,33 +57,33 @@ Check out our test results:
 
 ## Documentation
 
-Up-to-date documentation for the MongooseIM master branch can be found on ReadTheDocs: [https://mongooseim.readthedocs.io/en/latest/](https://mongooseim.readthedocs.io/en/latest/).
+Up-to-date documentation for the MongooseIM master branch can be found on ReadTheDocs: [https://esl.github.io/MongooseDocs/latest/](https://esl.github.io/MongooseDocs/latest/).
 
 Latest releases:
-* [4.0.1](https://mongooseim.readthedocs.io/en/4.0.1/)
-* [3.7.1](https://mongooseim.readthedocs.io/en/3.7.1/)
-* [3.6.2](https://mongooseim.readthedocs.io/en/3.6.2/)
-* [3.5.0](https://mongooseim.readthedocs.io/en/3.5.0/)
-* [3.4.0](https://mongooseim.readthedocs.io/en/3.4.0/)
-* [3.3.0](https://mongooseim.readthedocs.io/en/3.3.0/)
-* [3.2.0](https://mongooseim.readthedocs.io/en/3.2.0/)
-* [3.1.0](https://mongooseim.readthedocs.io/en/3.1.0/)
-* [3.0.0](https://mongooseim.readthedocs.io/en/3.0.0/)
+* [4.0.1](https://esl.github.io/MongooseDocs/4.0.1/)
+* [3.7.1](https://esl.github.io/MongooseDocs/3.7.1/)
+* [3.6.2](https://esl.github.io/MongooseDocs/3.6.2/)
+* [3.5.0](https://esl.github.io/MongooseDocs/3.5.0/)
+* [3.4.1](https://esl.github.io/MongooseDocs/3.4.1/)
+* [3.3.0](https://esl.github.io/MongooseDocs/3.3.0/)
+* [3.2.0](https://esl.github.io/MongooseDocs/3.2.0/)
+* [3.1.1](https://esl.github.io/MongooseDocs/3.1.1/)
+* [3.0.1](https://esl.github.io/MongooseDocs/3.0.1/)
 
 
 **MongooseIM documentation highligts:**
 
 When developing new features/modules, please make sure you add basic documentation to the 'doc/' directory, and add a link to your document in 'doc/README.md.'
 
-* [Tutorials](https://mongooseim.readthedocs.io/en/latest/user-guide/How-to-build/). Learn how to:
+* [Tutorials](https://esl.github.io/MongooseDocs/latest/user-guide/How-to-build/). Learn how to:
     * [Build MongooseIM from source code](doc/user-guide/How-to-build.md)
     * [Set up MongoosePush](doc/user-guide/push-notifications/Push-notifications.md)
     * [Set up MongooseICE](doc/user-guide/ICE_tutorial.md)
     * [Build an iOS messaging app](doc/user-guide/iOS_tutorial.md)
-* [User Guide](https://mongooseim.readthedocs.io/en/latest/user-guide/ABCs-of-MongooseIM/). Learn all about how to use MongooseIM in your project. Explore its features, supported XEPs, RFCs and database backends, as well as its architecture and deployment strategies.
-* [Configuration](https://mongooseim.readthedocs.io/en/latest/Basic-configuration/). Explore some of the available options including database backend configuration, access control lists, listener and extension modules.
-* [REST API](https://mongooseim.readthedocs.io/en/latest/rest-api/Client-frontend/). Explore MongooseIM features using our REST API and [Swagger documentation](https://mongooseim.readthedocs.io/en/latest/swagger/index.html).
-* [Operation and maintenance](https://mongooseim.readthedocs.io/en/latest/operation-and-maintenance/Cluster-management-considerations/). See what to consider when building, monitoring, testing and distributing MongooseIM clusters.
+* [User Guide](https://esl.github.io/MongooseDocs/latest/user-guide/ABCs-of-MongooseIM/). Learn all about how to use MongooseIM in your project. Explore its features, supported XEPs, RFCs and database backends, as well as its architecture and deployment strategies.
+* [Configuration](https://esl.github.io/MongooseDocs/latest/Basic-configuration/). Explore some of the available options including database backend configuration, access control lists, listener and extension modules.
+* [REST API](https://esl.github.io/MongooseDocs/latest/rest-api/Client-frontend/). Explore MongooseIM features using our REST API and [Swagger documentation](https://esl.github.io/MongooseDocs/latest/swagger/index.html).
+* [Operation and maintenance](https://esl.github.io/MongooseDocs/latest/operation-and-maintenance/Cluster-management-considerations/). See what to consider when building, monitoring, testing and distributing MongooseIM clusters.
 * [Server developer's guide](doc/developers-guide/Testing-MongooseIM.md). Get all the information you need to expand MongooseIM platform.
 
 

doc/Advanced-configuration.md → doc/advanced-configuration/configuration-files.md

@@ -12,17 +12,17 @@ This [TOML](https://github.com/toml-lang/toml) file contains the configuration o
 
 The file is divided into the following sections:
 
-* [**general**](advanced-configuration/general.md) - Served XMPP domains, log level, server language and some other miscellaneous settings.
-* [**listen**](advanced-configuration/listen.md) - Configured listeners, receiving incoming XMPP and HTTP connections.
-* [**auth**](advanced-configuration/auth.md) - Supported client authentication methods and their options.
-* [**outgoing_pools**](advanced-configuration/outgoing-connections.md) - Outgoing connections to external services, including databases, message queues and HTTP services.
-* [**services**](advanced-configuration/Services.md) - Internal services like an administration API and system metrics.
-* [**modules**](advanced-configuration/Modules.md) - [XMPP extension](https://xmpp.org/extensions/) modules, which extend the basic functionality provided by XMPP.
-* [**shaper**](advanced-configuration/shaper.md) - Traffic shapers that limit the incoming XMPP traffic, providing a safety valve to protect the server.
-* [**acl**](advanced-configuration/acl.md) - Access classes to which connecting users are assigned.
-* [**access**](advanced-configuration/access.md) - Access rules, specifying the privileges of the defined access classes.
-* [**s2s**](advanced-configuration/s2s.md) - Server-to-server connection options, used for XMPP federation.
-* [**host_config**](advanced-configuration/host_config.md) - Configuration options that need to be different for a specific XMPP domain.
+* [**general**](general.md) - Served XMPP domains, log level, server language and some other miscellaneous settings.
+* [**listen**](listen.md) - Configured listeners, receiving incoming XMPP and HTTP connections.
+* [**auth**](auth.md) - Supported client authentication methods and their options.
+* [**outgoing_pools**](outgoing-connections.md) - Outgoing connections to external services, including databases, message queues and HTTP services.
+* [**services**](Services.md) - Internal services like an administration API and system metrics.
+* [**modules**](Modules.md) - [XMPP extension](https://xmpp.org/extensions/) modules, which extend the basic functionality provided by XMPP.
+* [**shaper**](shaper.md) - Traffic shapers that limit the incoming XMPP traffic, providing a safety valve to protect the server.
+* [**acl**](acl.md) - Access classes to which connecting users are assigned.
+* [**access**](access.md) - Access rules, specifying the privileges of the defined access classes.
+* [**s2s**](s2s.md) - Server-to-server connection options, used for XMPP federation.
+* [**host_config**](host_config.md) - Configuration options that need to be different for a specific XMPP domain.
 
 The section names above are links to the detailed documentation of each section.
 
@@ -71,4 +71,4 @@ TLS is configured in one of two ways: some modules need a private key and certif
 
 In order to create private key & certificate bundle, you may simply concatenate them.
 
-More information about configuring TLS for these endpoints is available in the [listen section configuration](advanced-configuration/listen.md) page.
+More information about configuring TLS for these endpoints is available in the [listen section configuration](listen.md) page.

doc/css/custom.css

@@ -0,0 +1,9 @@
+img#mim-readme-logo {
+    margin-right: 1.5em;
+    margin-bottom: 1em;
+}
+
+:root {
+  --md-primary-fg-color: #459bb6;
+  --md-accent-fg-color: #0554b8;
+}

doc/css/version-select.css

@@ -0,0 +1,5 @@
+@media only screen and (max-width:76.1875em) {
+  #version-selector {
+    padding: .6rem .8rem;
+  }
+}

doc/index.md

@@ -1,9 +1,12 @@
 # MongooseIM platform
-[![Build Status](https://travis-ci.org/esl/MongooseIM.svg?branch=master)](https://travis-ci.org/esl/MongooseIM) [![Documentation Status](https://readthedocs.org/projects/mongooseim/badge/?version=latest)](https://mongooseim.readthedocs.org/en/latest/?badge=latest) [![codecov](https://codecov.io/gh/esl/MongooseIM/branch/master/graph/badge.svg)](https://codecov.io/gh/esl/MongooseIM) [![GitHub release](https://img.shields.io/github/release/esl/MongooseIM.svg)](https://github.com/esl/MongooseIM/releases)
 
-* Home: [http://github.com/esl/MongooseIM](http://github.com/esl/MongooseIM)
+[![Build Status](https://travis-ci.org/esl/MongooseIM.svg?branch=master)](https://travis-ci.org/esl/MongooseIM)
+[![codecov](https://codecov.io/gh/esl/MongooseIM/branch/master/graph/badge.svg)](https://codecov.io/gh/esl/MongooseIM)
+[![GitHub release](https://img.shields.io/github/release/esl/MongooseIM.svg)](https://github.com/esl/MongooseIM/releases)
+
+* Home: [https://github.com/esl/MongooseIM](https://github.com/esl/MongooseIM)
 * Product page: [https://www.erlang-solutions.com/products/mongooseim.html](https://www.erlang-solutions.com/products/mongooseim.html)
-* Documentation: [https://mongooseim.readthedocs.org/](https://mongooseim.readthedocs.org/)
+* Documentation: [https://esl.github.io/MongooseDocs/](https://esl.github.io/MongooseDocs/)
 
 
 ## Get to know MongooseIM
@@ -68,22 +71,20 @@ Check out our test results:
 * Load test history:
   ![Load test history](https://tide.erlang-solutions.com/charts/bidaily_last_year.png)
 
-
-
 ## Versions
 
 See the documentation for the latest releases:
 
-* [Master](https://mongooseim.readthedocs.org/en/latest/)
-* [4.0.1](https://mongooseim.readthedocs.io/en/4.0.1/)
-* [3.7.1](https://mongooseim.readthedocs.io/en/3.7.1/)
-* [3.6.2](https://mongooseim.readthedocs.io/en/3.6.2/)
-* [3.5.0](https://mongooseim.readthedocs.io/en/3.5.0/)
-* [3.4.0](https://mongooseim.readthedocs.io/en/3.4.0/)
-* [3.3.0](https://mongooseim.readthedocs.io/en/3.3.0/)
-* [3.2.0](https://mongooseim.readthedocs.io/en/3.2.0/)
-* [3.1.0](https://mongooseim.readthedocs.io/en/3.1.0/)
-* [3.0.0](https://mongooseim.readthedocs.io/en/3.0.0/)
+* [Master](https://esl.github.io/MongooseDocs/latest/)
+* [4.0.1](https://esl.github.io/MongooseDocs/4.0.1/)
+* [3.7.1](https://esl.github.io/MongooseDocs/3.7.1/)
+* [3.6.2](https://esl.github.io/MongooseDocs/3.6.2/)
+* [3.5.0](https://esl.github.io/MongooseDocs/3.5.0/)
+* [3.4.1](https://esl.github.io/MongooseDocs/3.4.1/)
+* [3.3.0](https://esl.github.io/MongooseDocs/3.3.0/)
+* [3.2.0](https://esl.github.io/MongooseDocs/3.2.0/)
+* [3.1.1](https://esl.github.io/MongooseDocs/3.1.1/)
+* [3.0.1](https://esl.github.io/MongooseDocs/3.0.1/)
 
 
 When developing new features/modules, please make sure you add basic documentation to the `doc/` directory, and add a link to your document in `doc/README.md.`

doc/js/version-select.js

@@ -0,0 +1,49 @@
+window.addEventListener("DOMContentLoaded", function() {
+  // This is a bit hacky. Figure out the base URL from a known CSS file the
+  // template refers to...
+  var ex = new RegExp("/?css/version-select.css$");
+  var sheet = document.querySelector('link[href$="version-select.css"]');
+
+  var ABS_BASE_URL = sheet.href.replace(ex, "");
+  var CURRENT_VERSION = ABS_BASE_URL.split("/").pop();
+
+  function makeSelect(options, selected) {
+    var select = document.createElement("select");
+    select.classList.add("form-control");
+
+    options.forEach(function(i) {
+      var option = new Option(i.text, i.value, undefined,
+                              i.value === selected);
+      select.add(option);
+    });
+
+    return select;
+  }
+
+  var xhr = new XMLHttpRequest();
+  xhr.open("GET", ABS_BASE_URL + "/../versions.json");
+  xhr.onload = function() {
+    var versions = JSON.parse(this.responseText);
+
+    var realVersion = versions.find(function(i) {
+      return i.version === CURRENT_VERSION ||
+             i.aliases.includes(CURRENT_VERSION);
+    }).version;
+
+    var select = makeSelect(versions.map(function(i) {
+      return {text: i.title, value: i.version};
+    }), realVersion);
+    select.addEventListener("change", function(event) {
+      window.location.href = ABS_BASE_URL + "/../" + this.value;
+    });
+
+    var container = document.createElement("div");
+    container.id = "version-selector";
+    container.className = "md-nav__item";
+    container.appendChild(select);
+
+    var sidebar = document.querySelector(".md-nav--primary > .md-nav__list");
+    sidebar.parentNode.insertBefore(container, sidebar);
+  };
+  xhr.send();
+});

doc/operation-and-maintenance/Reloading-configuration-on-a-running-system.md

@@ -33,6 +33,6 @@ The following options' changes will be ignored when using `mongooseimctl` tool:
 This option is deprecated and not available when using a config file in the TOML
 format.
 
-For the documentation of this option for the `cfg` config format please refer to
-the [MIM 3.7.1 documentation](https://mongooseim.readthedocs.io/en/3.7.1/operation-and-maintenance/Reloading-configuration-on-a-running-system/)
+For the documentation of this option for the `cfg` config format please refer to the
+[MIM 3.7.1 documentation](https://esl.github.io/MongooseDocs/3.7.1/operation-and-maintenance/Reloading-configuration-on-a-running-system/)
 or older.

doc/rest-api/Administration-backend.md

@@ -27,17 +27,17 @@ section of the [listeners](../advanced-configuration/listen.md) documentation.
 
 ## OpenAPI specifications
 
-Read the beautiful [Swagger documentation](http://mongooseim.readthedocs.io/en/latest/swagger/index.html) for more information.
+Read the beautiful [Swagger documentation](https://esl.github.io/MongooseDocs/latest/swagger/index.html) for more information.
 
-[![Swagger](http://nordicapis.com/wp-content/uploads/swagger-Top-Specification-Formats-for-REST-APIs-nordic-apis-sandoval-e1441412425742-300x170.png)](http://mongooseim.readthedocs.io/en/latest/swagger/index.html)
+[![Swagger](https://nordicapis.com/wp-content/uploads/swagger-Top-Specification-Formats-for-REST-APIs-nordic-apis-sandoval-e1441412425742-300x170.png)](https://esl.github.io/MongooseDocs/latest/swagger/index.html)
 
-<iframe src="http://mongooseim.readthedocs.io/en/latest/swagger/index.html"
+<iframe src="https://esl.github.io/MongooseDocs/latest/swagger/index.html"
 height="800" width="800" style="margin-left: -45px;" id="swagger-ui-iframe"></iframe>
 
 <script>
 
 $(document).ready(function() {
-  if (window.location.host.match("readthedocs")){
+  if (window.location.host.match("github")){
     path = window.location.pathname.match("(.*)/rest-api/Administration-backend")[1]
     url = window.location.protocol + "//" + window.location.hostname
     finalURL = url + path + "/swagger/index.html"