path: root/circuitpython/extmod/ulab/docs/ulab-convert.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "ExecuteTime": {
     "end_time": "2020-05-01T09:27:13.438054Z",
     "start_time": "2020-05-01T09:27:13.191491Z"
    }
   },
   "source": [
    "# conf.py"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2022-01-07T18:24:12.745063Z",
     "start_time": "2022-01-07T18:24:12.733067Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Overwriting manual/source/conf.py\n"
     ]
    }
   ],
   "source": [
    "%%writefile manual/source/conf.py\n",
    "# Configuration file for the Sphinx documentation builder.\n",
    "#\n",
    "# This file only contains a selection of the most common options. For a full\n",
    "# list see the documentation:\n",
    "# http://www.sphinx-doc.org/en/master/config\n",
    "\n",
    "# -- Path setup --------------------------------------------------------------\n",
    "\n",
    "# If extensions (or modules to document with autodoc) are in another directory,\n",
    "# add these directories to sys.path here. If the directory is relative to the\n",
    "# documentation root, use os.path.abspath to make it absolute, like shown here.\n",
    "#\n",
    "import os\n",
    "# import sys\n",
    "# sys.path.insert(0, os.path.abspath('.'))\n",
    "\n",
    "#import sphinx_rtd_theme\n",
    "\n",
    "from sphinx.transforms import SphinxTransform\n",
    "from docutils import nodes\n",
    "from sphinx import addnodes\n",
    "\n",
    "# -- Project information -----------------------------------------------------\n",
    "\n",
    "project = 'The ulab book'\n",
    "copyright = '2019-2022, Zoltán Vörös and contributors'\n",
    "author = 'Zoltán Vörös'\n",
    "\n",
    "# The full version, including alpha/beta/rc tags\n",
    "release = '4.0.0'\n",
    "\n",
    "\n",
    "# -- General configuration ---------------------------------------------------\n",
    "\n",
    "# Add any Sphinx extension module names here, as strings. They can be\n",
    "# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom\n",
    "# ones.\n",
    "extensions = [\n",
    "]\n",
    "\n",
    "# Add any paths that contain templates here, relative to this directory.\n",
    "templates_path = ['_templates']\n",
    "\n",
    "# List of patterns, relative to source directory, that match files and\n",
    "# directories to ignore when looking for source files.\n",
    "# This pattern also affects html_static_path and html_extra_path.\n",
    "exclude_patterns = []\n",
    "\n",
    "\n",
    "# Add any paths that contain custom static files (such as style sheets) here,\n",
    "# relative to this directory. They are copied after the builtin static files,\n",
    "# so a file named \"default.css\" will overwrite the builtin \"default.css\".\n",
    "html_static_path = ['_static']\n",
    "\n",
    "latex_maketitle = r'''\n",
    "\\begin{titlepage}\n",
    "\\begin{flushright}\n",
    "\\Huge\\textbf{The $\\mu$lab book}\n",
    "\\vskip 0.5em\n",
    "\\LARGE\n",
    "\\textbf{Release %s}\n",
    "\\vskip 5em\n",
    "\\huge\\textbf{Zoltán Vörös}\n",
    "\\end{flushright}\n",
    "\\begin{flushright}\n",
    "\\LARGE\n",
    "\\vskip 2em\n",
    "with contributions by\n",
    "\\vskip 2em\n",
    "\\textbf{Roberto Colistete Jr.}\n",
    "\\vskip 0.2em\n",
    "\\textbf{Jeff Epler}\n",
    "\\vskip 0.2em\n",
    "\\textbf{Taku Fukada}\n",
    "\\vskip 0.2em\n",
    "\\textbf{Diego Elio Pettenò}\n",
    "\\vskip 0.2em\n",
    "\\textbf{Scott Shawcroft}\n",
    "\\vskip 5em\n",
    "\\today\n",
    "\\end{flushright}\n",
    "\\end{titlepage}\n",
    "'''%release\n",
    "\n",
    "latex_elements = {\n",
    "    'maketitle': latex_maketitle\n",
    "}\n",
    "\n",
    "\n",
    "master_doc = 'index'\n",
    "\n",
    "author=u'Zoltán Vörös'\n",
    "copyright=author\n",
    "language='en'\n",
    "\n",
    "latex_documents = [\n",
    "(master_doc, 'the-ulab-book.tex', 'The $\\mu$lab book',\n",
    "'Zoltán Vörös', 'manual'),\n",
    "]\n",
    "\n",
    "# Read the docs theme\n",
    "on_rtd = os.environ.get('READTHEDOCS', None) == 'True'\n",
    "if not on_rtd:\n",
    "    try:\n",
    "        import sphinx_rtd_theme\n",
    "        html_theme = 'sphinx_rtd_theme'\n",
    "        html_theme_path = [sphinx_rtd_theme.get_html_theme_path(), '.']\n",
    "    except ImportError:\n",
    "        html_theme = 'default'\n",
    "        html_theme_path = ['.']\n",
    "else:\n",
    "    html_theme_path = ['.']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2021-05-09T06:06:28.491158Z",
     "start_time": "2021-05-09T06:06:28.477127Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Overwriting manual/source/index.rst\n"
     ]
    }
   ],
   "source": [
    "%%writefile manual/source/index.rst\n",
    "\n",
    ".. ulab-manual documentation master file, created by\n",
    "   sphinx-quickstart on Sat Oct 19 12:48:00 2019.\n",
    "   You can adapt this file completely to your liking, but it should at least\n",
    "   contain the root `toctree` directive.\n",
    "\n",
    "Welcome to the ulab book!\n",
    "=======================================\n",
    "\n",
    ".. toctree::\n",
    "   :maxdepth: 2\n",
    "   :caption: Introduction\n",
    "\n",
    "   ulab-intro\n",
    "\n",
    ".. toctree::\n",
    "   :maxdepth: 2\n",
    "   :caption: User's guide:\n",
    "\n",
    "   ulab-ndarray\n",
    "   numpy-functions\n",
    "   numpy-universal\n",
    "   numpy-fft\n",
    "   numpy-linalg\n",
    "   scipy-linalg\n",
    "   scipy-optimize\n",
    "   scipy-signal\n",
    "   scipy-special\n",
    "   ulab-utils\n",
    "   ulab-tricks\n",
    "   ulab-programming\n",
    "\n",
    "Indices and tables\n",
    "==================\n",
    "\n",
    "* :ref:`genindex`\n",
    "* :ref:`modindex`\n",
    "* :ref:`search`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Notebook conversion"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2022-01-07T18:24:27.671415Z",
     "start_time": "2022-01-07T18:24:24.933205Z"
    }
   },
   "outputs": [],
   "source": [
    "import nbformat as nb\n",
    "import nbformat.v4.nbbase as nb4\n",
    "from nbconvert import RSTExporter\n",
    "\n",
    "from jinja2 import FileSystemLoader\n",
    "rstexporter = RSTExporter(\n",
    "    extra_loaders=[FileSystemLoader('./templates')],\n",
    "    template_file = './templates/manual.tpl'\n",
    ")\n",
    "\n",
    "def convert_notebook(fn):\n",
    "    source = nb.read(fn+'.ipynb', nb.NO_CONVERT)\n",
    "    notebook = nb4.new_notebook()\n",
    "    notebook.cells = []\n",
    "    append_cell = False\n",
    "    for cell in source['cells']:\n",
    "        if append_cell:\n",
    "            notebook.cells.append(cell)\n",
    "        else:\n",
    "            if cell.cell_type == 'markdown':\n",
    "                if cell.source == '__END_OF_DEFS__':\n",
    "                    append_cell = True\n",
    "                    \n",
    "    (rst, resources) = rstexporter.from_notebook_node(notebook)\n",
    "    with open('./manual/source/' + fn + '.rst', 'w') as fout:\n",
    "        # it's a bit odd, but even an emtpy notebook is converted into a \"None\" string\n",
    "        rst = rst.lstrip('None')\n",
    "        fout.write(rst)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2022-01-07T19:52:29.910335Z",
     "start_time": "2022-01-07T19:52:28.432391Z"
    }
   },
   "outputs": [],
   "source": [
    "files = ['ulab-intro',\n",
    "         'ulab-ndarray',\n",
    "         'numpy-functions', \n",
    "         'numpy-universal',\n",
    "         'numpy-fft',\n",
    "         'numpy-linalg',\n",
    "         'scipy-linalg',\n",
    "         'scipy-optimize',\n",
    "         'scipy-signal',\n",
    "         'scipy-special',\n",
    "         'ulab-utils',\n",
    "         'ulab-tricks',\n",
    "         'ulab-programming']\n",
    "\n",
    "for file in files:\n",
    "    convert_notebook(file)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Template"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "ExecuteTime": {
     "end_time": "2020-10-30T19:04:50.295563Z",
     "start_time": "2020-10-30T19:04:50.227535Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Overwriting ./templates/manual.tpl\n"
     ]
    }
   ],
   "source": [
    "%%writefile ./templates/manual.tpl\n",
    "\n",
    "{%- extends 'display_priority.tpl' -%}\n",
    "\n",
    "\n",
    "{% block in_prompt %}\n",
    "{% endblock in_prompt %}\n",
    "\n",
    "{% block output_prompt %}\n",
    "{% endblock output_prompt %}\n",
    "\n",
    "{% block input scoped%}\n",
    "\n",
    "{%- if cell.source.split('\\n')[0].startswith('%%micropython') -%}\n",
    ".. code::\n",
    "        \n",
    "{{ '\\n'.join(['# code to be run in micropython'] + cell.source.strip().split('\\n')[1:]) | indent}}\n",
    "\n",
    "{%- else -%}\n",
    ".. code::\n",
    "\n",
    "{{ '\\n'.join(['# code to be run in CPython\\n'] + cell.source.strip().split('\\n')) | indent}}\n",
    "{%- endif -%}\n",
    "{% endblock input %}\n",
    "\n",
    "{% block error %}\n",
    "::\n",
    "\n",
    "{{ super() }}\n",
    "{% endblock error %}\n",
    "\n",
    "{% block traceback_line %}\n",
    "{{ line | indent | strip_ansi }}\n",
    "{% endblock traceback_line %}\n",
    "\n",
    "{% block execute_result %}\n",
    "{% block data_priority scoped %}\n",
    "{{ super() }}\n",
    "{% endblock %}\n",
    "{% endblock execute_result %}\n",
    "\n",
    "{% block stream %}\n",
    ".. parsed-literal::\n",
    "\n",
    "{{ output.text | indent }}\n",
    "{% endblock stream %}\n",
    "\n",
    "{% block data_svg %}\n",
    ".. image:: {{ output.metadata.filenames['image/svg+xml'] | urlencode }}\n",
    "{% endblock data_svg %}\n",
    "\n",
    "{% block data_png %}\n",
    ".. image:: {{ output.metadata.filenames['image/png'] | urlencode }}\n",
    "{%- set width=output | get_metadata('width', 'image/png') -%}\n",
    "{%- if width is not none %}\n",
    "   :width: {{ width }}px\n",
    "{%- endif %}\n",
    "{%- set height=output | get_metadata('height', 'image/png') -%}\n",
    "{%- if height is not none %}\n",
    "   :height: {{ height }}px\n",
    "{%- endif %}\n",
    "{% endblock data_png %}\n",
    "\n",
    "{% block data_jpg %}\n",
    ".. image:: {{ output.metadata.filenames['image/jpeg'] | urlencode }}\n",
    "{%- set width=output | get_metadata('width', 'image/jpeg') -%}\n",
    "{%- if width is not none %}\n",
    "   :width: {{ width }}px\n",
    "{%- endif %}\n",
    "{%- set height=output | get_metadata('height', 'image/jpeg') -%}\n",
    "{%- if height is not none %}\n",
    "   :height: {{ height }}px\n",
    "{%- endif %}\n",
    "{% endblock data_jpg %}\n",
    "\n",
    "{% block data_markdown %}\n",
    "{{ output.data['text/markdown'] | convert_pandoc(\"markdown\", \"rst\") }}\n",
    "{% endblock data_markdown %}\n",
    "\n",
    "{% block data_latex %}\n",
    ".. math::\n",
    "\n",
    "{{ output.data['text/latex'] | strip_dollars | indent }}\n",
    "{% endblock data_latex %}\n",
    "\n",
    "{% block data_text scoped %}\n",
    ".. parsed-literal::\n",
    "\n",
    "{{ output.data['text/plain'] | indent }}\n",
    "{% endblock data_text %}\n",
    "\n",
    "{% block data_html scoped %}\n",
    ".. raw:: html\n",
    "\n",
    "{{ output.data['text/html'] | indent }}\n",
    "{% endblock data_html %}\n",
    "\n",
    "{% block markdowncell scoped %}\n",
    "{{ cell.source | convert_pandoc(\"markdown\", \"rst\") }}\n",
    "{% endblock markdowncell %}\n",
    "\n",
    "{%- block rawcell scoped -%}\n",
    "{%- if cell.metadata.get('raw_mimetype', '').lower() in resources.get('raw_mimetypes', ['']) %}\n",
    "{{cell.source}}\n",
    "{% endif -%}\n",
    "{%- endblock rawcell -%}\n",
    "\n",
    "{% block headingcell scoped %}\n",
    "{{ (\"#\" * cell.level + cell.source) | replace('\\n', ' ') | convert_pandoc(\"markdown\", \"rst\") }}\n",
    "{% endblock headingcell %}\n",
    "\n",
    "{% block unknowncell scoped %}\n",
    "unknown type  {{cell.type}}\n",
    "{% endblock unknowncell %}\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "interpreter": {
   "hash": "ce9a02f9f7db620716422019cafa4bc1786ca85daa298b819f6da075e7993842"
  },
  "kernelspec": {
   "display_name": "Python 3",
   "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.5"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {
    "height": "calc(100% - 180px)",
    "left": "10px",
    "top": "150px",
    "width": "382.797px"
   },
   "toc_section_display": true,
   "toc_window_display": true
  },
  "varInspector": {
   "cols": {
    "lenName": 16,
    "lenType": 16,
    "lenVar": 40
   },
   "kernels_config": {
    "python": {
     "delete_cmd_postfix": "",
     "delete_cmd_prefix": "del ",
     "library": "var_list.py",
     "varRefreshCmd": "print(var_dic_list())"
    },
    "r": {
     "delete_cmd_postfix": ") ",
     "delete_cmd_prefix": "rm(",
     "library": "var_list.r",
     "varRefreshCmd": "cat(var_dic_list()) "
    }
   },
   "types_to_exclude": [
    "module",
    "function",
    "builtin_function_or_method",
    "instance",
    "_Feature"
   ],
   "window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}