Documentation

Author: xpqz

DEVELOPMENT.md

@@ -2,6 +2,10 @@
 
 This is a [Jupyter](http://jupyter.org/) kernel for [Dyalog APL](https://www.dyalog.com/). The [wiki](https://github.com/Dyalog/dyalog-jupyter-kernel/wiki) has more details. 
 
+For complete installation instructions from scratch on Windows, see [WINDOWS.md](WINDOWS.md) in this repository.
+
+If you're a kernel developer, see [DEVELOPMENT.md](DEVELOPMENT.md) in this repository.
+
 ## Do you have any pre-made notebook documents?
 
 A collection of ready-made notebooks is available [here](https://github.com/Dyalog/dyalog-jupyter-notebooks).
@@ -20,7 +24,7 @@ This kernel is installable via Python's package installer, [pip](https://pip.pyp
 In your terminal, run the follwing command:
 
 ```sh
-pip install dyalog-jupyter-kernel[==2.0.0]
+pip install dyalog-jupyter-kernel[==2.0.1]
 ```
 
 After successfully installing the kernel module itself, you need to register it with your Jupyter installation, using the following terminal command:
@@ -43,58 +47,4 @@ Start Jupyter:
 ```sh
 jupyter lab # or jupyter notebook
 ```
-and you should now see Dyalog APL amongst your kernels. Click on the Dyalog APL icon.
-
-## Build notes (kernel developer interest only)
-
-Build release assets with
-
-```sh
-python setup.py sdist bdist_wheel
-```
-
-Built assets will end up in `dist/`, and you can instruct `pip` to install from file for testing:
-
-```sh
-pip install dist/dyalog-jupyter-kernel-x.y.z.tar.gz
-```
-
-Upload release assets using [twine](https://twine.readthedocs.io/en/stable/). Install `twine` with 
-
-```sh
-pip install twine
-```
-
-Pick up the API token, and set up your `$HOME/.pypirc` file like this:
-
-```
-[distutils]
-index-servers =
-  pypi
-  testpypi
-
-[pypi]
-username = __token__
-password = pypi-A...Z  # Replace with your actual PyPI API token
-
-[testpypi]
-repository = https://test.pypi.org/legacy/
-username = __token__
-password = pypi-A...Z  # Replace with your actual TestPyPI API token
-```
-
-Use the API key as password, including the `pypi-` prefix.
-
-Upload the release:
-
-```sh
-twine upload --repository [test]pypi dist/*
-```
-
-To install the module from the test index, use
-
-```sh
-pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple dyalog-jupyter-kernel[==2.0.0]
-python -m 'dyalog_kernel' install
-```
-The `--extra-index-url` argument is there so that `pip` can pick up any dependencies from the main index.
+and you should now see Dyalog APL amongst your kernels. Click on the Dyalog APL icon.

README.md

@@ -0,0 +1,50 @@
+# A full installation, from scratch, on Windows
+
+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 (on Windows) 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 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/).
+3. Open a PowerShell terminal. Type the following steps into the terminal window.
+4. Create a virtual Python environment with a name of your choosing, for example
+    ```
+    python -m venv jupy312
+    ```
+5. Activate the virtual environment -- this is important:
+    ```
+    jupy312\Scripts\activate
+    ```
+    Your terminal prompt should change to have a `(jupy312)` prefix.
+6. Upgrade `pip` to the latest version:
+    ```
+    python.exe -m pip installl --upgrade pip
+    ```
+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:
+    ```
+    jupyter lab
+    ```
+
+A browser window should open up with the Jupyter Lab application. Click the "Dyalog APL" symbol to open a new notebook document with the Dyalog kernel.
+
+Once you're done working with Jupyter Lab, deactivate the Python environment:
+
+```
+deactivate
+```
+
+To start up Jupyter Lab again, you need to run `jupy312\Scripts\activate` and `jupyter lab` again. 

WINDOWS.md

@@ -1,5 +1,5 @@
 """Dyalog APL Jupyter kernel"""
 
-__version__ = '0.911'
+__version__ = '2.0.1'
 
 from .kernel import DyalogKernel