Merge pull request #100 from Dyalog/docs

Docs

Author: xpqz

DOCS.md

@@ -0,0 +1,33 @@
+# Building the docs
+
+Make a Python virtual environment, e.g.
+
+```sh
+mkdir ~/.venv
+python -m venv ~/.venv/docs
+. ~/.venv/docs/bin/activate
+```
+
+Install the following python modules:
+
+```sh
+pip install --upgrade pip
+pip install mkdocs
+pip install mkdocs-material
+```
+
+To build:
+```sh
+mkdocs build
+```
+
+View locally:
+```sh
+mkdocs serve
+```
+access at http://127.0.0.1:8000
+
+Deploy:
+```sh
+mkdocs gh-deploy
+```

docs/assets/apl385.ttf

@@ -0,0 +1,54 @@
+@font-face {
+	font-family: APL;
+	src: local("APL385 Unicode"), url("../assets/apl385.ttf");
+}
+.language-APL {
+	font-family: APL!important;
+	line-height: 1.2em!important;
+}
+code {
+	font-family: APL;
+	font-size: 1em!important;
+	padding-left: 0em!important;
+	padding-right: 0em!important;
+}
+.md-logo > img{
+	width: 7rem!important;
+	height: 1.2rem!important;
+}
+@media screen and (max-width: 76.1875em) {
+	.md-logo > img{
+		width: 10rem!important;
+		height: 1.8rem!important;
+	}
+}
+td:first-child {
+	white-space: nowrap;
+}
+table.scrollable {
+	display:block;
+	overflow-x: auto;
+	white-space: nowrap;
+}
+/* Custom colors */
+:root {
+	--md-primary-fg-color: #ED7F00;
+	--md-primary-fg-color--dark: #563336;
+	--md-default-bg-color: #F8F8F8;
+}
+/* Code copy only input (see CONTRIBUTING.md) */
+pre + pre > button, pre + hr {
+    display: none!important;
+}
+pre > code {
+    padding-bottom: 1em!important;
+}
+hr + pre > button {
+    top: -0.2em!important;
+}
+pre + pre , hr + pre {
+    margin-top: -1.8em!important;
+}
+pre + pre > code, hr + pre > code {
+    padding-top: 0.2em!important;
+}

docs/css/main.css

@@ -0,0 +1,19 @@
+# About
+
+## What are Jupyter notebooks?
+A Jupyter notebook document combines an interactive coding session with narrative text according to [Donald Knuth's *literate programming*](https://en.wikipedia.org/wiki/Literate_programming) paradigm.
+
+This is a nice format for teaching APL, explaining algorithms, and sharing ideas. The consumer of a notebook can experiment with the code, and make changes to the text and republish the notebook.
+
+## What is the Dyalog Jupyter kernel?
+Jupyter originated as a system for use with the **Julia**, **Python** and **R** programming languages (**JuPy**te**R**). To use the system with other programming languages, an interface between the Jupyter system and the language system (compiler, interpreter and what have you) is required. This interface is the language kernel.
+
+## How do I use Jupyter notebooks?
+Jupyter notebook documents can be used in the following ways:
+
+- You can [install](./install.md) the Jupyter system locally on your machine to write and interactively use notebooks - this means that you can edit the text and execute the code examples within the notebooks.
+- View the notebooks and execute the code [online](./online.md) in a dedicated sandboxed environment.
+- View or share the notebook as a static document, for example using [nbviewer](http://nbviewer.jupyter.org/).
+- Export notebooks to widely supported formats, such as HTML or PDF, in [local offline usage](./install.md) or in [Binder](./online.md#using-binder).  
+
+	> Open the *File* menu, click on *Download as* and select format. Note that some target formats may require installation of third party tools.

docs/img/dyalog-white.svg

@@ -0,0 +1,74 @@
+# Install and use locally
+
+**Dyalog version 15.0 or later** and **Python version 3.8+**, and the **jupyterlab** Python package must be installed in order to use the Dyalog Jupyter kernel.
+
+Installing, operating and maintaining a Python installation can be a bit of a chore, especially if you're not a Python developer. If you're coming to this wanting only to use Jupyter for Dyalog APL, here are some step by step instructions for how to set up the whole tool chain from scratch. 
+
+If you're a Python developer, or if you're already using a "canned" Python distribution, like [conda](https://docs.conda.io/en/latest/), you probably know what you're doing and can skip this document.
+
+The below instructions show how to install Jupyter and the Dyalog kernel inside a Python "virtual environment". This means that you can keep your Jupyter work separate from any other Python work, current or future. This is usually a good idea when working with Python.
+
+1. Download and install the [Dyalog interpreter](https://www.dyalog.com/download-zone.htm). 
+2. Download, and run the official [Python installer](https://www.python.org/downloads/). Ensure you select `Use admin privileges to install Python`, `Add python.exe to PATH`, and `Disable PATH limit`.
+3. Open a  terminal (e.g. PowerShell if you're on Windows). Type the following steps into the terminal window.
+4. Create a virtual Python environment with a name of your choosing, e.g.
+    ```
+    python -m venv jupy312
+    ```
+5. Activate the virtual environment -- this is important:
+    ```
+    jupy312\Scripts\activate # Windows
+	. jupy312/bin/activate   # linux, macOS. Note leading dot.
+    ```
+    Your terminal prompt should change to have a `(jupy312)` prefix.
+6. [Optional, but recommended] Upgrade `pip` to the latest version:
+    ```
+    python.exe -m pip installl --upgrade pip # Windows
+    python -m pip installl --upgrade pip     # linux, macOS
+    ```
+7. Install `jupyterlab`:
+    ```
+    pip install jupyterlab
+    ```
+8. Install the Dyalog kernel Python module:
+    ```
+    pip install dyalog-jupyter-kernel
+    ```
+9. Register the kernel with Jupyter:
+    ```
+    python -m 'dyalog_kernel' install
+    ```
+10. Start jupyterlab (or notebook):
+    ```
+	cd path/to/my/notebooks/
+    jupyter lab # or jupyter notebook
+    ```
+
+Jupyter lab (and notebook) uses a web interface. It has a drop-down button labeled *New▾* where you can choose to create a new Dyalog APL notebook. You can also navigate to and click on any existing notebook (a file with the `.ipynb` extension) to open it.
+
+## Troubleshooting
+
+### Python is not found
+> If you get the message
+> ```
+> python : The term 'python' is not recognized as the name of a cmdlet, function,  script file, or operable program.
+> ```
+> Run the installer again. Make sure to tick **Add Python to environment variables**
+
+### Cannot assign requsted address
+> If you get the message  
+> `OSError: [Errno 99] Cannot assign requested address`  
+> try:  
+> `jupyter-notebook --ip=0.0.0.0 --port=8080`  
+> or some other port number.
+
+## Entering APL characters
+
+You can get an APL language bar and enable key-bindings and character compositions using just a [a bookmarklet](https://abrudz.github.io/lb/apl) (a browser bookmark that contains commands which add new features to the browser). After adding the bookmarklet to your language bar, and opening a Jupyter notebook document in your browser, click on the bookmarklet. You can now insert APL characters in three ways:
+
+1. Click a symbol on the language bar.
+1. Type *Backtick* (`` ` ``) and then the associated symbol (hover over symbols on the language bar to see associations), e.g. *Backtick*+*r* makes `⍴` and *Backtick*+*Shift*+*e* makes `⍷`.
+1. Type two symbols which roughly make up the APL symbol, then press the *Tab* key to combine them. The two symbols are chosen to be easy to guess according to one of the following systems:
+    1. The symbols roughly make up the APL symbol when overlaid. For example, `O-` *Tab* makes `⊖` and `A|`*Tab*  makes `⍋`.
+    1. The symbols roughly make up the APL symbol when juxtaposed. For example, `<>` *Tab* makes `⋄` and `[]` *Tab* makes `⎕`
+    1. The symbols are identical, and are visually similar to the APL symbol. For example, `ee` makes `∊` and `xx` makes `×`.