Convert docstring from rst to markdown (#382)

* add coversion scripts to exclusion for ruff

* fix ordered list in contributing guide, fix visible frames of docker-compose for frontend, scheduler & worker

---------

Co-authored-by: sga <s.gyulmamedov@gmail.com>

Author: wm-wm-wm

Makefile

@@ -187,3 +187,9 @@ docs-fresh: docs-cleanup docs-build ##@Docs Cleanup & build docs
 
 docs-openapi: ##@Docs Generate OpenAPI schema
 	${PYTHON} -m syncmaster.server.scripts.export_openapi_schema docs/_static/openapi.json
+
+mddocs-build: mddocs-openapi ##@Docs Generate mkdocs documentation
+	PYTHONPATH=. DISABLE_MKDOCS_2_WARNING=true ${VIRTUAL_ENV}/bin/mkdocs build --strict --config-file mddocs/mkdocs.yml
+
+mddocs-openapi: ##@Docs Generate OpenAPI schema for mkdocs documentation
+	${PYTHON} -m syncmaster.server.scripts.export_openapi_schema mddocs/docs/_static/openapi.json

mddocs/_static/openapi.json

@@ -0,0 +1,55 @@
+.mermaid {
+  cursor: zoom-in;
+  }
+
+.mermaid-zoom-overlay {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100vw;
+  height: 100vh;
+  background: rgba(0, 0, 0, 0.85);
+  overflow: auto;
+  z-index: 9999;
+  padding: 48px 2vw 2vh;
+  box-sizing: border-box;
+  }
+
+.mermaid-zoom-toolbar {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100vw;
+  z-index: 10000;
+  display: flex;
+  gap: 8px;
+  padding: 8px 12px;
+  background: rgba(0, 0, 0, 0.7);
+  box-sizing: border-box;
+  }
+
+.mermaid-zoom-toolbar button {
+  background: rgba(255, 255, 255, 0.15);
+  color: white;
+  border: 1px solid rgba(255, 255, 255, 0.4);
+  border-radius: 4px;
+  padding: 4px 12px;
+  font-size: 16px;
+  cursor: pointer;
+  line-height: 1;
+  }
+
+.mermaid-zoom-toolbar button:hover {
+  background: rgba(255, 255, 255, 0.3);
+  }
+
+.mermaid-zoom-toolbar .mermaid-zoom-close {
+  margin-left: auto;
+  }
+
+.mermaid-zoom-overlay svg {
+  display: block;
+  background: white;
+  height: auto;
+  cursor: default;
+  }

mddocs/changelog.md

@@ -0,0 +1,91 @@
+(function () {
+  var shadowRoots = new WeakMap();
+  var _attachShadow = Element.prototype.attachShadow;
+  Element.prototype.attachShadow = function (init) {
+    var shadow = _attachShadow.call(this, init);
+    shadowRoots.set(this, shadow);
+    return shadow;
+  };
+
+  var ZOOM_STEPS = [100, 150, 200, 300];
+
+  document.addEventListener("click", function (e) {
+    if (e.target.closest(".mermaid-zoom-overlay") || e.target.closest(".mermaid-zoom-toolbar")) return;
+
+    var path = e.composedPath();
+    var container = null;
+    for (var i = 0; i < path.length; i++) {
+      var el = path[i];
+      if (el.classList && el.classList.contains("mermaid")) {
+        container = el;
+        break;
+      }
+    }
+    if (!container) return;
+
+    var root = container.shadowRoot || shadowRoots.get(container);
+    if (!root) return;
+    var svg = root.querySelector("svg");
+    if (!svg) return;
+
+    var currentStep = 1; // start at 150%
+
+    var overlay = document.createElement("div");
+    overlay.className = "mermaid-zoom-overlay";
+
+    var toolbar = document.createElement("div");
+    toolbar.className = "mermaid-zoom-toolbar";
+
+    var btnMinus = document.createElement("button");
+    btnMinus.textContent = "−";
+    var btnPlus = document.createElement("button");
+    btnPlus.textContent = "+";
+    var btnClose = document.createElement("button");
+    btnClose.textContent = "✕";
+    btnClose.className = "mermaid-zoom-close";
+
+    toolbar.appendChild(btnMinus);
+    toolbar.appendChild(btnPlus);
+    toolbar.appendChild(btnClose);
+
+    var clone = svg.cloneNode(true);
+    clone.removeAttribute("width");
+    clone.removeAttribute("height");
+    clone.style.width = ZOOM_STEPS[currentStep] + "%";
+
+    overlay.appendChild(clone);
+    document.body.appendChild(toolbar);
+    document.body.appendChild(overlay);
+
+    function updateZoom() {
+      clone.style.width = ZOOM_STEPS[currentStep] + "%";
+      btnMinus.disabled = currentStep === 0;
+      btnPlus.disabled = currentStep === ZOOM_STEPS.length - 1;
+    }
+
+    btnMinus.addEventListener("click", function (e) {
+      e.stopPropagation();
+      if (currentStep > 0) { currentStep--; updateZoom(); }
+    });
+    btnPlus.addEventListener("click", function (e) {
+      e.stopPropagation();
+      if (currentStep < ZOOM_STEPS.length - 1) { currentStep++; updateZoom(); }
+    });
+    btnClose.addEventListener("click", function (e) {
+      e.stopPropagation();
+      close();
+    });
+
+    overlay.addEventListener("click", close);
+
+    function close() {
+      overlay.remove();
+      toolbar.remove();
+      document.removeEventListener("keydown", onKey);
+    }
+    function onKey(e) { if (e.key === "Escape") close(); }
+    document.addEventListener("keydown", onKey);
+
+    updateZoom();
+  });
+})();