use GitHub Actions to deploy nimble guide. (#1197)

.github/workflows/binaries.yml

@@ -4,10 +4,11 @@ on:
  - 'v*' # "v1.2.3"
  branches:
  - master
- paths-ignore: ['media/**', 'docs/**', '**/*.md']
- pull_request:
- paths-ignore: ['media/**', 'docs/**', '**/*.md']
- workflow_dispatch:
+ paths-ignore: ['nimble-guide/**', '**/*.md']
+ pull_request:
+ paths-ignore: ['nimble-guide/**', '**/*.md']
+ workflow_dispatch:
+
 jobs:
  build:
  strategy:
@@ -79,6 +80,7 @@ jobs:
  path: nimble-${{ matrix.target.name }}.tar.gz
 
  create-github-release:
+ if: github.event_name != 'pull_request'
  name: Create GitHub Release
  needs: [build]
  runs-on: ubuntu-latest

.github/workflows/docs.yml

@@ -0,0 +1,41 @@
+name: GitHub Pages
+
+on:
+ push:
+ paths:
+ - 'nimble-guide/**'
+ workflow_dispatch:
+
+
+jobs:
+ build:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-python@v5
+ with:
+ python-version: '3.11'
+ cache: 'pip' # caching pip dependencies
+ - run: pip install -r nimble-guide/requirements.txt
+
+ - name: Build Docs
+ run: mkdocs build -f nimble-guide/mkdocs.yml
+
+ - name: Upload artifact
+ uses: actions/upload-pages-artifact@v2
+ with:
+ path: ./nimble-guide/site
+
+ deploy:
+ needs: build
+ permissions:
+ pages: write
+ id-token: write
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ runs-on: ubuntu-latest
+ steps:
+ - name: Deploy to GitHub Pages
+ id: deployment
+ uses: actions/deploy-pages@v2

.github/workflows/test.yml

@@ -1,6 +1,8 @@
 on:
  push:
+ paths-ignore: ['nimble-guide/**', '**/*.md']
  pull_request:
+ paths-ignore: ['nimble-guide/**', '**/*.md']
  schedule:
  - cron: "0 19 * * *"
 

.gitignore

@@ -8,6 +8,7 @@
 *.swp
 *~
 nimcache/
+.venv
 
 # Absolute paths
 /src/babel
@@ -67,4 +68,4 @@ src/nimblepkg/version
 
 # Nimble Guide files
 nimble-guide/site/
-!Makefile
+!nimble-guide/config.nims

nimble-guide/README.md

@@ -0,0 +1,19 @@
+# Nimble Guide
+
+## Contributing
+
+In order to preview changes to the guide you will need to have `python` installed.
+With python you should generate a local `venv` and install `mkdocs-material`:
+
+```sh
+python -m venv .venv && ./.venv/bin/pip install -r ./requirements.txt
+source ./.venv/bin/activate
+mkdocs serve
+```
+
+To automate `venv` usage and `mkdocs` install you can use the tasks defined in [`config.nims`](./config.nims) and just run:
+
+```sh
+nim serve
+```
+

nimble-guide/config.nims

@@ -0,0 +1,25 @@
+import std/[os, strformat]
+
+const
+ binDir = when defined(windows): "Scripts" else: "bin"
+ python = toExe("python")
+ pip = ".venv" / binDir / toExe("pip")
+ mkdocs = ".venv" / binDir / toExe("mkdocs")
+
+task bootstrap, "set up mkdocs":
+ exec fmt"{python} -m venv .venv"
+ exec fmt"{pip} install -r requirements.txt"
+
+proc ensureMkdocs() =
+ if not fileExists mkdocs:
+ echo "no mkdocs found, generating local venv"
+ bootstrapTask()
+
+task serve, "serve guide w/mkdocs":
+ ensureMkdocs()
+ exec fmt"{mkdocs} serve"
+
+task build, "build guide w/mkdocs":
+ ensureMkdocs()
+ exec fmt"{mkdocs} build"
+

nimble-guide/requirements.txt

@@ -0,0 +1 @@
+mkdocs-material>=9.5