📖 Initial User Facing Documentation (#164)

* 🌱 seeding the docs, adding a note on figures, images and cell attachments

* wip: add initial workflow to build docs

* 📓 minimal index page

* 🪛 fix image paths

* 📦 Delete package-lock (we are using yarn!)

* 📖 Typos

* Minor updates

* ci: deploy docs

---------

Co-authored-by: stevejpurves <[email protected]>
Co-authored-by: Angus Hollands <[email protected]>

.github/workflows/deploy.yml

@@ -0,0 +1,46 @@
+# This file was created automatically with `myst init --gh-pages` 🪄 💚
+
+name: MyST GitHub Pages Deploy
+on:
+  push:
+    # Runs on pushes targeting the default branch
+    branches: [main]
+env:
+  # `BASE_URL` determines the website is served from, including CSS & JS assets
+  # You may need to change this to `BASE_URL: ''`
+  BASE_URL: /${{ github.event.repository.name }}
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: 'pages'
+  cancel-in-progress: false
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18.x
+      - name: Install MyST Markdown
+        run: npm install -g mystmd
+      - name: Build HTML Assets
+        run: myst build --html
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: './_build/html'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

docs/figures.md

@@ -0,0 +1,50 @@
+---
+title: Images and figures
+description: MyST Markdown allows you to create images and figures in your documents, including cross-referencing content throughout your pages.
+thumbnail: ./thumbnails/todo.png
+---
+
+MyST Markdown can be used to include images and figures in your notebooks as well as referencing those images easily in other cells of the notebook.
+
+```{tip}
+For a general description of the MyST figures and image directives see the [main MyST Markdown docs](https://mystmd.org/guide/figures) at <https://mystmd.org>, read on for notebook specific considerations.
+```
+
+## Simple Images
+
+Adding an image to your notebook using the standard Markdown syntax will work as usual with the standard markdown syntax:
+
+```markdown
+![alt](link 'title')
+```
+
+## Figure Directives
+
+By switching to MyST Directives or figures (and images) can be inserted with some additional control. `figure`s can also be cross-referenced in other places in the notebook. For example, the following `figure`:
+
+```{myst}
+:::{figure} https://source.unsplash.com/random/400x200?beach,ocean
+:name: myFigure
+:alt: Random image of the beach or ocean!
+:align: center
+
+Randomized beach and ocean images from Unsplash 🏖
+:::
+
+Check out [](#myFigure)!!
+```
+
+Has a `name` attribute allows you to cross-reference the figure from any other markdown cell in the notebook using the familiar markdown link syntax (see the documentation on [Cross References](https://mystmd.org/guide/cross-references)).
+The `figure` directive is similar to `image` but allows for a caption and sequential figure numbering.
+
+## Cell Attachments
+
+Notebooks allow images to be added as cell attachments. This is typically achieved via drag and drop in the notebook interface and results in the image being added to the notebook itself as a base64 encoded string.
+
+Cell attachments are inserted into the notebook using standard markdown syntax such as:
+
+```{md}
+![image.png](attachment:7c0e625d-6238-464f-8100-8d008f30848b.png)
+```
+
+These links are inserted automatically by jupyter when an attachment is added. Once the link syntax is known these can be changed to `image` or `figure` directives where captions can be added attributes can be used to, for example control the image size. Attachments are cell specific, so this will only work in the same cell that the attachment was added.

docs/index.md

@@ -0,0 +1,92 @@
+---
+title: MyST extension for JupyterLab
+description: The MyST Markdown JupyterLab extension switches the default markdown rendering in JupyterLab to MyST. Allowing notebook authors to create richer content using MyST roles and directives alongside plain markdown to create notebook based content from technical tutorials though to publication-quality documents with bibliography support.
+---
+
+Render markdown cells using [MyST Markdown](https://mystmd.org/), including support for rich frontmatter, interactive references, admonitions, figure numbering, tabs, cards, and grids!
+
+![](../images/walkthrough.gif)
+
+## Requirements
+
+- JupyterLab >= 4.0
+
+## Install
+
+To install the extension, execute:
+
+```bash
+pip install jupyterlab_myst
+```
+
+## Features
+
+`jupyterlab-myst` is a fully featured markdown renderer for technical documents, [get started with MyST Markdown](https://mystmd.org/docs/mystjs/quickstart-myst-markdown). It supports the MyST `{eval}` inline role, which facilitates the interweaving of code outputs and prose. For example, we can use inline expressions to explore the properties of a NumPy array.
+
+In the code cell:
+
+```python
+import numpy as np
+array = np.arange(4)
+```
+
+In the markdown cell:
+
+```markdown
+Let's consider the following array: {eval}`array`.
+
+We can compute the total: {eval}`array.sum()` and the maximum value is {eval}`array.max()`.
+```
+
+This will evaluate inline, and show:
+
+```text
+Let's consider the following array: array([0, 1, 2, 3]).
+
+We can compute the total: 6 and the maximum value is 3.
+```
+
+You can also use this with `ipywidgets`, and have inline interactive text:
+
+![](../images/cookies.gif)
+
+Or with `matplotlib` to show inline spark-lines:
+
+![](../images/stock-price.gif)
+
+You can also edit task-lists directly in the rendered markdown.
+
+![](../images/tasklists-in-jupyterlab.gif)
+
+## Usage
+
+[MyST][myst-quickstart] is a flavour of Markdown, which combines the experience of writing Markdown with the programmable extensibility of reStructuredText. This extension for JupyterLab makes it easier to develop rich, computational narratives, technical documentation, and open scientific communication.
+
+### Execution 🚀
+
+To facilitate inline expressions, `jupyterlab-myst` defines a `jupyterlab-myst:executor` plugin. This plugin sends expression code fragments to the active kernel when the user "executes" a Markdown cell. To disable this functionality, disable the `jupyterlab-myst:executor` plugin with:
+
+```bash
+jupyter labextension disable jupyterlab-myst:executor
+```
+
+### Trust 🕵️‍♀️
+
+Jupyter Notebooks implement a [trust-based security model](https://jupyter-notebook.readthedocs.io/en/stable/security.html). With the addition of inline expressions, Markdown cells are now considered when determining whether a given notebook is "trusted". Any Markdown cell with inline-expression metadata (with display data) is considered "untrusted". Like outputs, expression results are rendered using safe renderers if the cell is not considered trusted.
+Executing the notebook will cause each cell to be considered trusted.
+
+To facilitate this extension of the trust model, the `jupyterlab_myst` server extension replaces the `NotebookNotary` from `nbformat` with `MySTNotebookNotary`. This can be disabled with
+
+```bash
+jupyter server extension disable jupyterlab-myst
+```
+
+The `MySTNotebookNotary` adds additional code that makes it possible to mark Markdown cells as trusted.
+
+## Uninstall
+
+To remove the extension, execute:
+
+```bash
+pip uninstall jupyterlab_myst
+```

docs/myst.yml

@@ -0,0 +1,31 @@
+# See docs at: https://mystmd.org/docs/mystjs/frontmatter
+version: 1
+project:
+  title: jupyterlab-myst
+  description: Write MyST in JupyterLab Notebooks. This extension replaces the default markdown rendering enabling the rich features of MyST to be used in Markdown cells.
+  keywords: []
+  authors: []
+  github: https://github.com/executablebooks/jupyterlab-myst
+  references:
+    python: https://docs.python.org/3.7/
+    jupyterbook: https://jupyterbook.org/en/stable/
+    guide: https://mystmd.org/guide/
+    spec: https://mystmd.org/spec/
+  abbreviations:
+    AST: Abstract Syntax Tree
+    DOI: Digital Object Identifier
+    MyST: Markedly Structured Text
+    CLI: Command Line Interface
+    HTML: Hypertext Markup Language
+    PDF: Portable Document Format
+    YAML: Yet Another Markup Language
+    REES: Reproducible Execution Environment Specification
+    RST: reStructuredText
+site:
+  template: book-theme
+  nav: []
+  actions:
+    - title: Learn More
+      url: https://mystmd.org/jupyterlab
+  domains:
+    - mystmd-jupyterlab.curve.space