update docs

Author: saveli

.gitignore

@@ -507,3 +507,5 @@ bin/native/osx-x64/libsecp256k1.dylib
 bin/native/osx-arm64/libsecp256k1.dylib
 bin/native/linux-x64/libsecp256k1.so
 bin/native/linux-arm64/libsecp256k1.so
+docs/.venv-pandoc/
+.DS_Store

docs/index.html

@@ -271,7 +271,7 @@ NOVA provides several statistical meassures to investigate the agreement between
 
 	where $K$ defines the number of components (K-items or testlets) 
 
-	$\bar{r}$ is the mean of the $K(K-1)/2} K(K-1)/2$ non-redundant correlation coefficients
+	$\bar{r}$ is the mean of the $K(K-1)/2$ non-redundant correlation coefficients
 
 * Spearman Correlation:
 
@@ -357,8 +357,8 @@ We will describe two strategies: a) set up MongoDB with Docker *or* b) set up Mo
 First, we install Docker (<https://www.docker.com/>) and run:
 
 ~~~~
-docker pull mongo:3.6.0  
-docker run -d -p 27017-27019:27017-27019 --name nova mongo:3.6.0
+docker pull mongo:3.6  
+docker run -d --restart unless-stopped -p 27017-27019:27017-27019 --name nova mongo:3.6
 
 
 ~~~~
@@ -377,12 +377,13 @@ MongoDB now runs on 127.0.0.1:27017 and we can connect to it:
 
 
 ~~~~
-
 docker exec -it nova bash
+~~~~
 
-Enter:
-mongo
+*Press <kbd>Enter</kbd>.*
 
+~~~~
+mongo
 ~~~~
 
 *or*
@@ -397,10 +398,12 @@ We add an administrator:
 use admin
 db.createUser({ user: 'admin', pwd: 'PASSWORD', roles: [ { role: "root", db: "admin" } ],  customData: {fullname: "ADMIN", email: ' ', expertise: NumberInt(0)}}); 
 exit
+~~~~
 
-Enter:
-exit
+*Press <kbd>Enter</kbd>.*
 
+~~~~
+exit
 ~~~~
 
 And reconnect afterwards:
@@ -440,11 +443,39 @@ db.createUser({ user: 'gold', pwd: 'PASSWORD1', roles: [ { role: "readWriteAnyDa
 db.createUser({ user: 'system', pwd: 'PASSWORD2', roles: [ { role: "readWriteAnyDatabase", db: "admin" }, {"role" : "changeOwnPasswordCustomDataRole", "db" : "admin"} ], customData: {fullname: 'SYSTEM', email: ' ', expertise: NumberInt(0)} });
 ~~~~			
 
-We can now test the server:		
+We can now test the server:
 
-~~~~			
+~~~~
 show dbs
-~~~~			
+~~~~
+
+If MongoDB runs on a different machine than NOVA, we recommend enabling TLS. A minimal container setup is:
+
+1) Create a server certificate and key on the MongoDB host (use your CA or self-signed for testing) and place them in one PEM file, e.g. `mongo.pem`.
+
+2) Start MongoDB with TLS enabled:
+
+~~~~
+docker run -d --restart unless-stopped \
+  -p 27017:27017 \
+  -v /path/to/certs:/certs:ro \
+  --name nova \
+  mongo:3.6.0 \
+  --auth \
+  --tlsMode requireTLS \
+  --tlsCertificateKeyFile /certs/mongo.pem \
+  --tlsCAFile /certs/ca.pem
+~~~~
+
+3) Connect with TLS from NOVA or the shell (example):
+
+~~~~
+mongo --tls --host <mongo-host> --port 27017 \
+  --tlsCAFile /path/to/ca.pem \
+  -u admin -p PASSWORD --authenticationDatabase admin
+~~~~
+
+Make sure the host name in the certificate matches the address NOVA uses to connect (or include it in the certificate SANs).
 
 To connect to the MongoDB server in NOVA, we open the settings by clicking the wheel in the menu and switch to the 'Database' tab. Here we enter the host and port number of the MongoDB server and the user credentials. The dialog also allows it to customize the download and CML directory. After applying the changes, NOVA tries to connect to MongoDB. If a connection is established it will be displayed in the status bar.
 

docs/index.md

@@ -1,4 +1,4 @@
 @echo off
 cd /D "%~dp0"
 
-pandoc -o index.html -s -f markdown --number-sections --template templates/standalone.html --css templates/template.css --toc --toc-depth=4 --mathjax  index.md
+pandoc -o index.html -s -f markdown --number-sections --template templates/standalone.html --css templates/template.css --toc --toc-depth=4 --mathjax=https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml-full.js index.md

docs/make-html.cmd

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "${BASH_SOURCE[0]}")"
+
+VENV_DIR=".venv-pandoc"
+
+if [[ ! -d "$VENV_DIR" ]]; then
+  python3 -m venv "$VENV_DIR"
+fi
+
+# shellcheck disable=SC1091
+source "$VENV_DIR/bin/activate"
+
+python -m pip install --upgrade pip >/dev/null
+python -m pip install --quiet pypandoc-binary >/dev/null
+
+python - <<'PY'
+import pypandoc
+
+pypandoc.convert_file(
+    "index.md",
+    "html",
+    outputfile="index.html",
+    extra_args=[
+        "-s",
+        "-f", "markdown",
+        "--number-sections",
+        "--template", "templates/standalone.html",
+        "--css", "templates/template.css",
+        "--toc",
+        "--toc-depth=4",
+        "--mathjax=https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml-full.js",
+    ],
+)
+PY
+
+echo "Wrote index.html"

docs/make-html.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "${BASH_SOURCE[0]}")"
+
+VENV_DIR=".venv-pandoc"
+
+if [[ ! -d "$VENV_DIR" ]]; then
+  python3 -m venv "$VENV_DIR"
+fi
+
+# shellcheck disable=SC1091
+source "$VENV_DIR/bin/activate"
+
+python -m pip install --upgrade pip >/dev/null
+python -m pip install --quiet pypandoc-binary >/dev/null
+
+python - <<'PY'
+import pypandoc
+
+pypandoc.convert_file(
+    "index.md",
+    "pdf",
+    outputfile="index.pdf",
+    extra_args=[
+        "-s",
+        "--number-sections",
+        "--toc",
+        "--toc-depth=4",
+        "--template=templates/default.latex",
+        "-V", "documentclass=scrartcl",
+    ],
+)
+PY
+
+echo "Wrote index.pdf"

docs/make-latex.sh

@@ -24,7 +24,6 @@
 <link href="templates/menu/css/skins/graphite.css" rel="stylesheet" type="text/css" />
 <link href="templates/menu/css/skins/grey.css" rel="stylesheet" type="text/css" />
 
-<script src="templates/menu/js/MathJax.js"></script>
 
 
   <script src="templates/script.js"></script>