Merge pull request #251 from alexarchambault/update-doc

Add install from sources instructions

docs/pages/dev-from-sources.md

@@ -0,0 +1,67 @@
+---
+title: Installing from sources
+---
+
+## Prerequisites
+
+Ensure a JDK 8 is installed on your machine
+```bash
+$ java -version
+java version "1.8.0_121"
+Java(TM) SE Runtime Environment (build 1.8.0_121-b13)
+Java HotSpot(TM) 64-Bit Server VM (build 25.121-b13, mixed mode)
+$ javac -version
+javac 1.8.0_121
+```
+
+Ensure an [sbt](https://scala-sbt.org) launcher is installed
+```bash
+$ sbt -help
+Usage: sbt [options]
+
+[…]
+```
+If it's not, [sbt-extras](https://github.com/paulp/sbt-extras) or the default installer from [the sbt website](https://scala-sbt.org) should do.
+
+## Compiling
+
+Check-out the sources with
+```bash
+$ git clone https://github.com/almond-sh/almond.git
+$ cd almond
+```
+
+Compile and publish the kernel locally with
+```bash
+$ sbt publishLocal
+```
+This installs the kernel artifacts under your `~/.ivy2/local` local repository. The kernel artifacts should land under `~/.ivy2/local/sh.almond/` in particular. In the output of `sbt publishLocal`, note the snapshot version the kernel is installed with. At the time of writing this, this version is `0.1.11-SNAPSHOT`.
+
+## Installing
+
+Create a launcher with
+```bash
+$ SCALA_VERSION=2.12.7 ALMOND_VERSION=0.1.11-SNAPSHOT
+$ coursier bootstrap \
+    -i user -I user:sh.almond:scala-kernel-api_$SCALA_VERSION:$ALMOND_VERSION \
+    sh.almond:scala-kernel_$SCALA_VERSION:$ALMOND_VERSION \
+    -o almond-snapshot --embed-files=false
+```
+Compared to [the default installation instructions](quick-start-install.md), `--embed-files=false` is added as an option. This makes the generated launcher directly rely on files under `~/.ivy2/local`, rather than copying those in the launcher. If the files under `~/.ivy2/local` are updated (e.g. with a new `sbt publishLocal`), just restarting the kernel is enough for these to be picked, which is useful for fast iterations during development.
+
+Then install the kernel with
+```bash
+$ ./almond-snapshot --install \
+    --id scala-snapshot \
+    --display-name "Scala (snapshot)" \
+    --log debug \
+    --log-to "$(pwd)/almond-snapshot-log.txt"
+```
+
+Optionally, change the log level with e.g. `--log debug`. If you'd like these logs to go to a distinct file rather than in the console, pass e.g. `--log-to "/path/to/log-file.txt"`.
+
+## Development cycle
+
+Once the kernel is installed this way, one can update its artifacts with `sbt publishLocal`. These are taken into account by restarting the kernel.
+
+Re-generating an installer, and installing it, is only necessary if the dependencies of the kernel are changed / updated, or if the kernel version changes. It is safer to re-generate an installer and install it after a `git pull` in particular.

docs/pages/dev-website.md

@@ -0,0 +1,39 @@
+---
+title: Generate the website
+---
+
+Install pre-requisites with
+```bash
+$ sbt \
+    interpreter-api/exportVersions \
+    interpreter-api/publishLocal \
+    scala-kernel-api/publishLocal
+```
+
+Then run
+```bash
+$ scripts/generate-website.sh
+```
+
+If the generation is successful, this should print instructions to run
+a small webserver serving the website, like
+```bash
+$ npx http-server docs/website/build/almond
+```
+
+This command should itself print the address to access the local website,
+like `http://127.0.0.1:8080`.
+
+## Watch sources
+
+Pass `--watch` to `generate-website.sh` above,
+```bash
+$ scripts/generate-website.sh --watch
+```
+
+In another terminal, go under the `docs/website` directory, and run
+```bash
+$ yarn start
+```
+
+This should open a browser window, pointing at the locally running website.

docs/pages/quick-start-install.md

@@ -13,7 +13,7 @@ $ coursier bootstrap @EXTRA_COURSIER_ARGS@\
 
 See the available versions of almond [here](https://github.com/jupyter-scala/jupyter-scala/releases),
 adjust `ALMOND_VERSION` and `SCALA_VERSION` at your convenience (not all combinations are guaranteed
-to be available, see the available combinations [here](versions.md)).
+to be available, see the available combinations [here](install-versions.md)).
 
 Run the launcher like
 ```bash

docs/website/sidebars.json

@@ -3,6 +3,6 @@
     "Quick start": ["intro", "quick-start-install"],
     "Usage": ["usage-shell", "usage-jupyter", "usage-plotting", "usage-spark"],
     "Installation": ["install-options", "install-multiple", "install-versions", "install-other"],
-    "Development": ["dev-custom-kernel", "dev-libraries"]
+    "Development": ["dev-from-sources", "dev-custom-kernel", "dev-libraries", "dev-website"]
   }
 }

scripts/generate-website.sh

@@ -3,6 +3,12 @@ set -e
 
 # FIXME Lots of duplications with https://github.com/coursier/coursier/blob/3309b64102678550b1393c524dddf2b71fb9d931/scripts/generate-website.sh
 
+if [ "$1" == "--watch" ]; then
+  WATCH=1
+else
+  WATCH=0
+fi
+
 cd "$(dirname "${BASH_SOURCE[0]}")"
 
 # Assumes 'sbt interpreter-api/exportVersions' has been run
@@ -20,6 +26,12 @@ fi
 
 echo "Processing Markdown files"
 
+if [ "$WATCH" = 1 ]; then
+  EXTRA_OPTS="--watch"
+else
+  EXTRA_OPTS=""
+fi
+
 # first processing md files via https://github.com/olafurpg/mdoc
 # requires the cache modules and its dependencies to have been published locally
 # with
@@ -32,7 +44,12 @@ echo "Processing Markdown files"
     --out ../docs/processed-pages \
     --site.VERSION "$VERSION" \
     --site.SCALA_VERSION "$SCALA_VERSION" \
-    --site.EXTRA_COURSIER_ARGS "$EXTRA_COURSIER_ARGS"
+    --site.EXTRA_COURSIER_ARGS "$EXTRA_COURSIER_ARGS" \
+    $EXTRA_OPTS
+
+if [ "$WATCH" = 1 ]; then
+  exit 0
+fi
 
 echo "Generating website"