doc/raw-cells.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "nbsphinx": "hidden"
   },
   "source": [
    "This notebook is part of the `nbsphinx` documentation: https://nbsphinx.readthedocs.io/."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Raw Cells\n",
    "\n",
    "Any Jupyter Notebook consists of cells of three different types:\n",
    "[Code cells](./code-cells.ipynb),\n",
    "[Markdown cells](./markdown-cells.ipynb)\n",
    ", and/or Raw cells.\n",
    "While most Jupyter Notebook users are very familiar with Code cells and Markdown cells in Jupyter Notebooks, Raw cells are less frequently used.\n",
    "For Jupyter Notebook, they are introduced\n",
    "[here](https://jupyter-notebook.readthedocs.io/en/stable/notebook.html?highlight=raw#raw-cells)\n",
    "and for JupyterLab\n",
    "[here](https://jupyterlab.readthedocs.io/en/stable/extension/notebook.html?highlight=raw#model).\n",
    "The Raw cells are also sometimes referred to as Raw NBConvert cells in the context of\n",
    "[nbconvert](https://nbconvert.readthedocs.io/en/latest/architecture.html?highlight=raw#a-detailed-pipeline-exploration).\n",
    "The Raw cell type can be used to render different code formats into HTML or LaTeX by Sphinx.\n",
    "This information is stored in the notebook metadata and converted appropriately.\n",
    "\n",
    "## Usage\n",
    "\n",
    "Raw cells are created differently depending on the user interface.\n",
    "\n",
    "### Jupyter Notebook\n",
    "\n",
    "To select a desired format from within Jupyter Notebook, select the cell containing your special code and choose options from the following dropdown menus:\n",
    "\n",
    "1. Select \"Raw NBConvert\" in the Menu Toolbar (just below the two menus \"Widgets\" and \"Help\").\n",
    "2. Click on the \"Raw NBConvert Format\" dropdown menu within the cell and select \"reST\".\n",
    "\n",
    "![Steps for converting cells to Raw formats in Jupyter Notebook](images/raw_cells_jupyter_notebook.png)\n",
    "<!-- this comment makes pandoc create an in-line image -->\n",
    "\n",
    "### JupyterLab\n",
    "\n",
    "To select a desired format from within JupyterLab, first activate the right sidebar by clicking on View in the Menu Toolbar.\n",
    "Then you ensure that in front of Show Right Sidebar there is a tick.\n",
    "Once the Right Sidebar is shown, you are ready to go.\n",
    "\n",
    "Now you select the cell containing your special code and choose options from the following dropdown menus:\n",
    "\n",
    "1. Select \"Raw\" in the Notebook Toolbar (just next to the symbols that run cells or reload the kernel).\n",
    "2. Click on \"Raw NBConvert Format\" in the Right Sidebar and select \"reStructured Text\".\n",
    "\n",
    "![Steps for converting cells to Raw formats in JupyterLab](images/raw_cells_jupyterlab.png)\n",
    "<!-- this comment makes pandoc create an in-line image -->"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Available Raw Cell Formats\n",
    "\n",
    "The following examples show how different Jupyter cell formats are rendered by Sphinx."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### None\n",
    "\n",
    "By default (if no cell format is selected), the cell content is included (without any conversion) in both the HTML and LaTeX output.\n",
    "This is typically not useful at all."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "\"I'm a raw cell with no format.\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### reST\n",
    "\n",
    "Raw cells in \"reST\" format are interpreted as reStructuredText and parsed by Sphinx.\n",
    "Thus, you can e.g. use its\n",
    "[cross-referencing abilities](https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#cross-referencing-python-objects)\n",
    "for automatically creating/updating links to the definition of modules, classes, functions, and similar.\n",
    "The result is visible in both HTML and LaTeX output."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    "\"**I'm** a *raw cell* in reST_ format.\"\n",
    "\n",
    "I can contain Sphinx roles such as a link to :func:`example_python_function`.\n",
    "\n",
    ".. _reST: https://www.sphinx-doc.org/rest.html"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Markdown\n",
    "\n",
    "Raw cells in \"Markdown\" format are interpreted as Markdown, and the result is included in both HTML and LaTeX output.  Since the Jupyter Notebook also supports normal Markdown cells, this might not be useful *at all*."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/markdown"
   },
   "source": [
    "\"**I'm** a *raw cell* in [Markdown](https://daringfireball.net/projects/markdown/) format.\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### HTML\n",
    "\n",
    "Raw cells in \"HTML\" format are only visible in HTML output. This option might not be very useful, since raw HTML code is also allowed within normal Markdown cells."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/html"
   },
   "source": [
    "<p>&ldquo;<b>I&rsquo;m</b> a <em>raw cell</em> in\n",
    "<a href=\"https://www.w3.org/html/\">HTML</a> format.&rdquo;</p>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### LaTeX\n",
    "\n",
    "Raw cells in \"LaTeX\" format are only visible in LaTeX output."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/latex"
   },
   "source": [
    "\\textbf{I'm} a \\emph{raw cell} in \\href{https://www.latex-project.org/}{\\LaTeX} format."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Python\n",
    "\n",
    "Raw cells in \"Python\" format are not visible at all (nor executed in any way)."
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/x-python"
   },
   "source": [
    "print(\"I'm a raw cell in \\\"Python\\\" format!\")"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Raw Cell Format",
  "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.8.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}