add cmdrun

.github/workflows/cd-docs.yml

@@ -2,10 +2,7 @@ name: cd-docs
 
 on:
   workflow_dispatch:
-  push:
-    paths:
-      - 'documentation/docs/**'
-
+#TODO bring in changes from ci-docs
 jobs:
   build:
     runs-on: custom-linux
@@ -34,8 +31,11 @@ jobs:
             --vers "^1.8.0" mdbook-admonish && cargo install --vers \
             "^0.1.2" mdbook-last-changed && cargo install --vers "^0.1.2" mdbook-theme \
             && cargo install --vers "^0.7.7" mdbook-linkcheck
+      - name: Remove existing Nym config directory (`~/.nym/`)
+        run: cd documentation && ./remove_existing_config.sh
+        continue-on-error: false
       - name: Build all projects in documentation/ & move to ~/dist/docs/
-        run: cd documentation && ./build_all_to_dist.sh
+        run: ./build_all_to_dist.sh
         continue-on-error: false
 
       - name: Post process

.github/workflows/ci-docs-old.yml

@@ -0,0 +1,83 @@
+name: ci-docs
+
+on:
+  workflow_dispatch:
+  push:
+    branches-ignore: master
+    paths:
+      - 'documentation/docs/**'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Install Dependencies (Linux)
+        run: sudo apt-get update && sudo apt-get install -y build-essential curl wget libssl-dev libudev-dev squashfs-tools protobuf-compiler
+      - name: Install rsync
+        run: sudo apt-get install rsync
+      - uses: rlespinasse/github-slug-action@v3.x
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+      - name: Install Rust stable
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+      - name: Build all binaries
+        uses: actions-rs/cargo@v1
+        with:
+          command: build
+          args: --workspace --release
+      - name: Install mdbook
+        run: cargo install mdbook
+      - name: Install mdbook plugins
+        run: |
+          cargo install mdbook-variables
+          cargo install mdbook-admonish
+          cargo install mdbook-last-changed
+          cargo install mdbook-theme
+          cargo install mdbook-linkcheck
+        # TODO remove once we know we dont need it anymore
+            # && cd documentation \
+            # && mdbook-admonish install dev-portal \
+            # && mdbook-admonish install docs \
+            # && mdbook-admonish install operators
+#      - name: Remove existing Nym config directory (`~/.nym/`)
+#        run: cd documentation && ./remove_existing_config.sh
+#        continue-on-error: false
+      - name: Build all projects in documentation/ & move to ~/dist/docs/
+        run: cd documentation && ./build_all_to_dist.sh
+        continue-on-error: false
+
+      - name: Deploy branch to CI www
+        continue-on-error: true
+        uses: easingthemes/ssh-deploy@main
+        env:
+          SSH_PRIVATE_KEY: ${{ secrets.CI_WWW_SSH_PRIVATE_KEY }}
+          ARGS: "-rltgoDzvO --delete"
+          SOURCE: "dist/docs/"
+          REMOTE_HOST: ${{ secrets.CI_WWW_REMOTE_HOST }}
+          REMOTE_USER: ${{ secrets.CI_WWW_REMOTE_USER }}
+          TARGET: ${{ secrets.CI_WWW_REMOTE_TARGET }}/docs-${{ env.GITHUB_REF_SLUG }}
+          EXCLUDE: "/node_modules/"
+      - name: Matrix - Node Install
+        run: npm install
+        working-directory: .github/workflows/support-files
+      - name: Matrix - Send Notification
+        env:
+          NYM_NOTIFICATION_KIND: ci-docs
+          NYM_PROJECT_NAME: "Docs CI"
+          NYM_CI_WWW_BASE: "${{ secrets.NYM_CI_WWW_BASE }}"
+          NYM_CI_WWW_LOCATION: "docs-${{ env.GITHUB_REF_SLUG }}"
+          GIT_COMMIT_MESSAGE: "${{ github.event.head_commit.message }}"
+          GIT_BRANCH: "${GITHUB_REF##*/}"
+          MATRIX_SERVER: "${{ secrets.MATRIX_SERVER }}"
+          MATRIX_ROOM: "${{ secrets.MATRIX_ROOM_DOCS }}"
+          MATRIX_USER_ID: "${{ secrets.MATRIX_USER_ID }}"
+          MATRIX_TOKEN: "${{ secrets.MATRIX_TOKEN }}"
+          MATRIX_DEVICE_ID: "${{ secrets.MATRIX_DEVICE_ID }}"
+          IS_SUCCESS: "${{ job.status == 'success' }}"
+        uses: docker://keybaseio/client:stable-node
+        with:
+          args: .github/workflows/support-files/notifications/entry_point.sh

.github/workflows/ci-docs.yml

@@ -9,9 +9,11 @@ on:
 
 jobs:
   build:
-    runs-on: custom-linux
+    runs-on: ubuntu-20.04-16core #custom-linux
     steps:
       - uses: actions/checkout@v3
+      - name: Install Dependencies (Linux)
+        run: sudo apt-get update && sudo apt-get install -y build-essential curl wget libssl-dev libudev-dev squashfs-tools protobuf-compiler
       - name: Install rsync
         run: sudo apt-get install rsync
       - uses: rlespinasse/github-slug-action@v3.x
@@ -28,21 +30,24 @@ jobs:
           command: build
           args: --workspace --release
       - name: Install mdbook
-        run: (test -x $HOME/.cargo/bin/mdbook || cargo install --vers "^0.4.35" mdbook)
-      - name: Install mdbook plugins
-        run: |
-          cargo install --vers "=0.2.2" mdbook-variables && cargo install \
-            --vers "^1.8.0" mdbook-admonish --force && cargo install --vers \
-            "^0.1.2" mdbook-last-changed && cargo install --vers "^0.1.2" mdbook-theme \
-            && cargo install --vers "^0.7.7" mdbook-linkcheck \
-            # && cd documentation \
-            # && mdbook-admonish install dev-portal \
-            # && mdbook-admonish install docs \
-            # && mdbook-admonish install operators
-
-      - name: Build all projects in documentation/ & move to ~/dist/docs/
-        run: cd documentation && ./build_all_to_dist.sh 
+        # TODO change to use script instead
+        run: cd documentation && ./install_mdbook_deps.sh # cargo install mdbook
+#      - name: Install mdbook plugins
+#        run: |
+#          cargo install mdbook-variables
+#          cargo install mdbook-admonish
+#          cargo install mdbook-last-changed
+#          cargo install mdbook-theme
+#          cargo install mdbook-linkcheck
+       # TODO check if this makes sense / you aren't blowing other things away
+      - name: Remove existing Nym config directory (`~/.nym/`)
+        run: cd documentation && ./remove_existing_config.sh
         continue-on-error: false
+      # TODO remove cd, we should already be there from the last command?
+      - name: Build all projects in documentation/ & move to ~/dist/docs/
+        run: cd documentation && ./build_all_to_dist.sh
+        continue-on-error: false
+
       - name: Deploy branch to CI www
         continue-on-error: true
         uses: easingthemes/ssh-deploy@main

documentation/README.md

@@ -6,11 +6,17 @@ Each directory contains a readme with more information about running and contrib
 * `dev-portal` contains developer documentation hosted at [https://nymtech.net/developers](https://nymtech.net/developers)
 * `operators` contains node setup and maintenance guides hosted at [https://nymtech.net/operators](https://nymtech.net/operators)
 
+> If you are looking for the Typescript SDK documentation located at [sdk.nymtech.net](https://sdk.nymtech.net) this can be found in `../sdk/typescript/docs/`
+
 ## Scripts 
 * `bump_versions.sh` allows you to update the ~~`platform_release_version` and~~ `wallet_release_version` variable~~s~~ in the `book.toml` of each mdbook project at once. You can also optionally update the `minimum_rust_version` as well. Helpful for lazy-updating when cutting a new version of the docs. 
-* `build_all_to_dist.sh` is used by the `ci-dev.yml` and `cd-dev.yml` scripts for building all mdbook projects and moving the rendered html to `../dist/` to be rsynced with various servers. 
-* `post_process.sh` is a script called by the github CI and CD workflows to post process CSS/image/href links for serving several mdbooks from a subdirectory. 
 
+* The following scripts are used by the `ci-dev.yml` and `cd-dev.yml` scripts:
+  * `build_all_to_dist.sh` is used for building all mdbook projects and moving the rendered html to `../dist/` to be rsynced with various servers. 
+  * `install_mdbook_deps.sh` checks for an existing install of mdbook (and plugins), uninstalls them, and then installs them on a clean slate. This is to avoid weird dependency clashes if relying on an existing mdbook version. 
+  * `post_process.sh` is used to post process CSS/image/href links for serving several mdbooks from a subdirectory. 
+
+[//]: # (  * `removed_existing_config.sh` is used to remove existing nym client/node config files on the CI/CD server so avoid `mdbook-cmdrun` command errors.  )
 
 ### Licensing and copyright information
 This is a monorepo and components that make up Nym as a system are licensed individually, so for accurate information, please check individual files.
@@ -20,4 +26,4 @@ As a general approach, licensing is as follows this pattern:
 - libraries and components are Apache 2.0 or MIT
 - documentation is Apache 2.0 or CC0-1.0
 
-For accurate information, please check individual files.
+For accurate information, please check individual files.

documentation/dev-portal/src/introduction.md

@@ -4,6 +4,6 @@ Welcome to the Nym Developer Portal, containing quickstart resources, user manua
 
 For more in-depth information about nodes, network traffic flows, clients, coconut etc check out the [docs](https://nymtech.net/docs). 
 
-If you are looking for information and setup guides for the various pieces of Nym mixnet infrastructure (mix nodes, gateways and network requesters) and Nyx blockchain validators see the **new [Operators Guides](https://nymtech.net/operators)** book. 
+If you are looking for information and setup guides for the various pieces of Nym mixnet infrastructure (mix nodes, gateways and network requesters) and Nyx blockchain validators see the [Operators Guides](https://nymtech.net/operators) book. 
 
-If you're looking for TypeScript/JavaScript related information such as SDKs to build your own tools, step-by-step tutorials, live playgrounds and more, make sure to check out the **new [TS SDK Handbook](https://sdk.nymtech.net/)** !
+If you're looking for TypeScript/JavaScript related information such as SDKs to build your own tools, step-by-step tutorials, live playgrounds and more, make sure to check out the  [TS SDK Handbook](https://sdk.nymtech.net/).

documentation/install_mdbook_deps.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+# simple script to automate cleaning an existing mdbook install then installing it fresh for each deploy.
+
+# pinning minor version to this: allows for updates but no breaking changes
+MINOR_VERSION=0.4
+# if a new plugin is added to the books it needs to be added here also
+declare -a plugins=("admonish" "linkcheck" "last-changed" "theme" "variables" "cmdrun")
+
+# install mdbook + plugins
+install_mdbook_deps() {
+	printf "\ninstalling mdbook..." 
+	# installing mdbook with only specific features for speed 
+	cargo install mdbook --no-default-features --features search --vers "^$MINOR_VERSION"
+
+	printf "\ninstalling plugins..." 
+	for i in "${plugins[@]}"
+	do
+		cargo install mdbook-$i
+	done
+
+# mdbook-admonish config
+#	if [ $(pwd | awk -F/ '{print $NF}') != "documentation" ]; then
+#		printf "not in documentation/ - changing dir but something isn't right in the workflow file"
+#  		cd documentation/
+#		mdbook-admonish install dev-portal
+#        	mdbook-admonish install docs
+#        	mdbook-admonish install operators
+#	else
+#        mdbook-admonish install dev-portal
+#        mdbook-admonish install docs
+#        mdbook-admonish install operators
+#	fi
+}
+
+# uninstall mdbook + plugins
+uninstall_mdbook_deps() {
+	# mdbook
+	printf "\nuninstalling existing mdbook installation...\n" 
+	cargo uninstall mdbook 
+	# check it worked 
+	if [ $? -ne 0 ]; then
+		printf "\nsomething went wrong, exiting"
+		exit 1
+	else 
+		printf "\nmdbook deleted\n"
+	fi
+
+	# plugins
+	printf "\nuninstalling existing plugins...\n"
+	for i in "${plugins[@]}"
+	do
+		cargo uninstall mdbook-$i
+		# check it worked
+		if [ $? -ne 0 ]; then 
+			printf "\nsomething went wrong, exiting"
+			exit 1
+		else 
+		printf "\nmdbook-$i deleted\n"
+	fi
+	done
+}
+
+main() {
+	if test -f ~/.cargo/bin/mdbook; then
+		printf "mdbook already installed (located at: $(which mdbook))"
+		uninstall_mdbook_deps;
+		install_mdbook_deps;
+	else 
+		printf "mdbook not installed"
+		install_mdbook_deps;
+	fi
+}
+
+main; 

documentation/remove_existing_config.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+# Script to remove existing ~'/.nym/ files on docs deployment. Used to avoid issues with `mdbook-cmdrun` output when
+# e.g. erroring about overwriting existing keys. `mdbook-cmdrun` output for the moment has to be checked manually.
+
+DIR=~/.nym
+
+# check for config directory
+if [ ! -d $DIR ]; then
+  echo "config dir doesn't exist: nothing to do"
+else
+  echo "config dir exists - deleting"
+  rm -rf $DIR
+  # check exit code of rm -rf - if !0 then exit
+  if [ $? -ne 0 ]; then
+    echo "exit code was $0. looks like the something went wrong with deleting the directory"
+    exit 1
+  fi
+fi