doc/specification.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "0b485b77-8077-4f99-8273-04cfede73c61",
   "metadata": {},
   "outputs": [],
   "source": [
    "# ---\n",
    "# jupyter:\n",
    "#   jupytext:\n",
    "#     text_representation:\n",
    "#       extension: .py\n",
    "#       format_name: percent\n",
    "#       format_version: '1.3'\n",
    "#   kernelspec:\n",
    "#     display_name: Python 3 (ipykernel)\n",
    "#     language: python\n",
    "#     name: python3\n",
    "# ---"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "68b5e61f-d1db-4a9e-9ffe-e55ef70372d7",
   "metadata": {},
   "source": [
    "# Neopyter specifications\n",
    "> The source of this notebook is `doc/specification.ju.py`\n",
    "\n",
    "This is a example file describe the specification of `.ju.py`. We will introduce some specifications and notices you need to learn.\n",
    "\n",
    "The main format supported  is the [percent](https://jupytext.readthedocs.io/en/latest/formats-scripts.html) format: cells can have\n",
    "\n",
    "* title\n",
    "* a cell type (`code`, `markdown`, `md` or `raw`, omitted for code cells)\n",
    "* and cell metadata\n",
    "\n",
    "Here is a example of cell separator(the percent format)\n",
    "```python\n",
    " # %% Optional title [cell type] key=\"value\"\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1f109181-906b-4fc1-a8fc-e37ae7f077d4",
   "metadata": {},
   "source": [
    "## Code Cell\n",
    "These are all legitimate code cells:\n",
    "* Default cell separtor\n",
    "```python\n",
    " # %%\n",
    "```\n",
    "* Cell separtor with title\n",
    "\n",
    "```python\n",
    " # %% title\n",
    "```\n",
    "E.g."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "5bdb9a99-bb62-4821-be8a-22f837dd6474",
   "metadata": {},
   "outputs": [],
   "source": [
    "import time"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "80e2ef1c-e1cc-4985-9f98-d4ec930a58f0",
   "metadata": {},
   "outputs": [],
   "source": [
    "def say(msg):\n",
    "    print(msg)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b58d0cff-36b3-4e4c-b51c-1de75eb327f3",
   "metadata": {},
   "source": [
    "### Cell Magic\n",
    "`Cell magic` is not a standard  of percent format, but for convenience, we support multiple formats\n",
    "<table width=\"90%\">\n",
    "<tr>\n",
    "<td> Code </td> <td> Notebook </td>  <td> Description </td>\n",
    "</tr>\n",
    "<tr>\n",
    "<td>\n",
    "\n",
    "```python\n",
    "# %%\n",
    "# %%js\n",
    "'''\n",
    "console.log(\"Hello\")\n",
    "console.log(\"Neopyter\")\n",
    "'''\n",
    "```\n",
    "\n",
    "</td>\n",
    "<td>\n",
    "\n",
    "![](./cell_magic_js.png)\n",
    "\n",
    "</td>\n",
    "\n",
    "<td>\n",
    "If the cell contains only one string, we extract the string as the content of the cell\n",
    "</td>\n",
    "</tr>\n",
    "<tr>\n",
    "<td> \n",
    "\n",
    "```python\n",
    "# %%\n",
    "# %%js\n",
    "# console.log(\"Hello\")\n",
    "# console.log(\"Neopyter\")\n",
    "```\n",
    "\n",
    "</td>\n",
    "<td>\n",
    "\n",
    "![](./cell_magic_js.png)\n",
    "\n",
    "</td>\n",
    "<td>\n",
    "If the cell contains only multiple comments, and all comments are start with `# `, we extract the comment as cell content.\n",
    "</td>\n",
    "</tr>\n",
    "<tr>\n",
    "<td> \n",
    "\n",
    "```python\n",
    "# %%\n",
    "# %%time\n",
    "a = 1 + 2\n",
    "time.sleep(1)\n",
    "```\n",
    "\n",
    "</td>\n",
    "<td>\n",
    "\n",
    "![](./cell_magic_time.png)\n",
    "\n",
    "</td>\n",
    "<td>\n",
    "Otherwise, we keep it as cell content.\n",
    "</td>\n",
    "</tr>\n",
    "<td> \n",
    "</table>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "9785aff9-576e-411d-a7c8-ce2f703cd8ae",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/javascript": [
       "console.log('Hello')\n",
       "console.log(\"Neopyter\")\n"
      ],
      "text/plain": [
       "<IPython.core.display.Javascript object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%%js\n",
    "console.log('Hello')\n",
    "console.log(\"Neopyter\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "0a216d92-7c16-4b1a-8f85-1cb8d0a43491",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/javascript": [
       "console.log('Hello')\n",
       "console.log(\"Neopyter\")\n"
      ],
      "text/plain": [
       "<IPython.core.display.Javascript object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%%js\n",
    "console.log('Hello')\n",
    "console.log(\"Neopyter\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "f417d6fa-8b8e-4a03-ab73-4688dce8888e",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "CPU times: user 6.86 ms, sys: 33 μs, total: 6.89 ms\n",
      "Wall time: 1 s\n"
     ]
    }
   ],
   "source": [
    "%%time\n",
    "time.sleep(1)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f30360bd-354d-4c9a-af21-ceb3df0183f7",
   "metadata": {},
   "source": [
    "### Line Magic\n",
    "We support line magic, you can write line magic with prefix `# `, e.g.\n",
    "```python\n",
    "# %time time.sleep(1)\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "aa0e2412-3bf6-472a-93d8-b29951293d01",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "CPU times: user 1.84 ms, sys: 343 μs, total: 2.18 ms\n",
      "Wall time: 1 s\n"
     ]
    }
   ],
   "source": [
    "%time time.sleep(1)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8c4eb5a7-6605-4027-840e-f61323140ac9",
   "metadata": {},
   "source": [
    "## Markdown Cell\n",
    "Neopyter support markdown cell to, `md` will be treated as `markdown`. We support multiple formats too.\n",
    "<table width=\"90%\">\n",
    "<tr>\n",
    "<td> Code </td> <td> Notebook </td>  <td> Description </td>\n",
    "</tr>\n",
    "<tr>\n",
    "<td>\n",
    "\n",
    "```python\n",
    "# %% [md]\n",
    "'''\n",
    "### Heading\n",
    "\n",
    "- list item 1\n",
    "- list item 2\n",
    "'''\n",
    "```\n",
    "\n",
    "</td>\n",
    "<td>\n",
    "\n",
    "![](./markdown_cell.png)\n",
    "\n",
    "</td>\n",
    "\n",
    "<td>\n",
    "If the cell contains only one string, we extract the string as the content of the cell\n",
    "</td>\n",
    "</tr>\n",
    "<tr>\n",
    "<td> \n",
    "\n",
    "```python\n",
    "# %% [markdown]\n",
    "# ### Heading\n",
    "\n",
    "# - list item 1\n",
    "# - list item 2\n",
    "```\n",
    "\n",
    "</td>\n",
    "<td>\n",
    "\n",
    "![](./markdown_cell.png)\n",
    "\n",
    "</td>\n",
    "<td>\n",
    "If the cell contains only multiple comments, and all comments are start with `# `, we extract the comment as cell content.\n",
    "</td>\n",
    "</tr>\n",
    "<tr>\n",
    "<td> \n",
    "\n",
    "```python\n",
    "# %% [markdown]\n",
    "### Heading\n",
    "\n",
    "print(\"Hello\")\n",
    "\n",
    "```\n",
    "\n",
    "</td>\n",
    "<td>\n",
    "\n",
    "![](./markdown_cell_simple.png)\n",
    "\n",
    "</td>\n",
    "<td>\n",
    "Otherwise, we keep it as cell content. Although this may cause some problems\n",
    "</td>\n",
    "</tr>\n",
    "<td> \n",
    "</table>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e0b74eb4-72aa-47ed-ada7-e4891e61d12f",
   "metadata": {},
   "source": [
    "### Heading\n",
    "\n",
    "- list item 1\n",
    "- list item 2"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c532a312-35ac-4a1f-a39e-d34056aa9386",
   "metadata": {},
   "source": [
    "### Heading\n",
    "\n",
    "- list item 1\n",
    "- list item 2"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "626c1618-d18c-4006-b17c-c05e415377f3",
   "metadata": {},
   "source": [
    "### Heading\n",
    "\n",
    "print(\"Hello\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7314cfeb-cd5c-4118-afc9-db04100a929d",
   "metadata": {},
   "source": [
    "## Raw Cell\n",
    "Raw cell fellow the same standard with markdown"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.13.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}