Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tonyfast/literacy
Interactive literate programming in the Jupyter notebooks
https://github.com/tonyfast/literacy
Last synced: about 1 month ago
JSON representation
Interactive literate programming in the Jupyter notebooks
- Host: GitHub
- URL: https://github.com/tonyfast/literacy
- Owner: tonyfast
- License: bsd-3-clause
- Created: 2017-06-10T20:29:26.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2017-11-30T22:54:11.000Z (about 7 years ago)
- Last Synced: 2024-12-29T15:10:58.133Z (about 2 months ago)
- Language: Jupyter Notebook
- Homepage:
- Size: 212 KB
- Stars: 7
- Watchers: 3
- Forks: 1
- Open Issues: 4
-
Metadata Files:
- Readme: readme.ipynb
- License: LICENSE
Awesome Lists containing this project
README
{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# __literacy__ - interactive literate programming in markdown\n",
"\n",
"> [`...`](http://roxygen.org/knuth-literate-programming.pdf) considering programs to be works of literature. `...` surely nobody wants to admit writing an _illiterate_ program.\n",
"> - _Donald Knuth_ - **Literate Programming** "
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Installation\n",
"\n",
"```bash\n",
"pip install git+https://github.com/tonyfast/literacy\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Literacy Programming Mode\n",
" "
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {
"collapsed": true
},
"outputs": [],
"source": [
"%reload_ext literacy"
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {},
"outputs": [
{
"data": {
"text/markdown": [
"```\n",
" %reload_ext literacy\n",
"```\n",
"\n",
"---\n",
" \n",
"`import literacy` accepts Markdown as source; the __inline__, __fenced__, __indented__ code objects are concatenated into a single block of __python__ \n",
"source code. _All code in this block is executed._\n",
"\n",
" bar = 42\n",
" print(bar)\n",
" assert literacy\n",
" \n",
"---"
],
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"42\n"
]
}
],
"source": [
"```\n",
" %reload_ext literacy\n",
"```\n",
"\n",
"---\n",
" \n",
"`import literacy` accepts Markdown as source; the __inline__, __fenced__, __indented__ code objects are concatenated into a single block of __python__ \n",
"source code. _All code in this block is executed._\n",
"\n",
" bar = 42\n",
" print(bar)\n",
" assert literacy\n",
" \n",
"---"
]
},
{
"cell_type": "code",
"execution_count": 3,
"metadata": {},
"outputs": [
{
"data": {
"text/markdown": [
"# Templating Mode\n",
"\n",
" %reload_ext literacy.template\n",
"\n",
"Template mode applies `__import__('jinja2');` to weave variables in scope into the markdown source."
],
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"# Templating Mode\n",
"\n",
" %reload_ext literacy.template\n",
"\n",
"Template mode applies `__import__('jinja2');` to weave variables in scope into the markdown source."
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {},
"outputs": [
{
"data": {
"text/markdown": [
"## More readable\n",
"\n",
"Use the templating system to explicitly write source, rather than implicit for loops.\n",
"\n",
" print(0); print(1); print(2); print(3); "
],
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"0\n",
"1\n",
"2\n",
"3\n"
]
}
],
"source": [
"## More readable\n",
"\n",
"Use the templating system to explicitly write source, rather than implicit for loops.\n",
"\n",
" {% for i in range(4) %}print({{i}}); {% endfor %}"
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {},
"outputs": [
{
"data": {
"text/markdown": [
"# Macros\n",
"\n",
"## yaml\n",
"\n",
"Begin a code block with --- to invoke yaml syntax as valid data input. _This is great for taking notes._\n",
"\n",
" ---\n",
" refs:\n",
" - roxygen.org/knuth-literate-programming.pdf\n",
" - https://en.wikipedia.org/wiki/Literate_programming\n",
" \n",
"> _The yaml source must contain named objects at the top level._"
],
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"# Macros\n",
"\n",
"## yaml\n",
"\n",
"Begin a code block with --- to invoke yaml syntax as valid data input. _This is great for taking notes._\n",
"\n",
" ---\n",
" refs:\n",
" - roxygen.org/knuth-literate-programming.pdf\n",
" - https://en.wikipedia.org/wiki/Literate_programming\n",
" \n",
"> _The yaml source must contain named objects at the top level._"
]
},
{
"cell_type": "code",
"execution_count": 6,
"metadata": {},
"outputs": [
{
"data": {
"text/markdown": [
"---\n",
" \n",
" if __name__ == '__main__':\n",
" \n",
"# Importable Literate Notebooks\n",
"\n",
" \n",
" import readme\n",
" \n",
"with the following tests \n",
"\n",
" assert readme.__file__ == 'readme.ipynb'\n",
" assert readme.bar is bar\n",
" bar = 3.14\n",
" assert readme.bar is not bar\n",
" \n",
"\n",
"---\n",
"\n",
"_`literacy;` makes it possible to import any notebook._\n",
"\n",
"---"
],
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"42\n",
"0\n",
"1\n",
"2\n",
"3\n"
]
},
{
"name": "stderr",
"output_type": "stream",
"text": [
"[NbConvertApp] Converting notebook readme.ipynb to markdown\n",
"[NbConvertApp] Writing 2381 bytes to readme.md\n"
]
},
{
"data": {
"text/markdown": [
"# This is literate source"
],
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"---\n",
" \n",
" if __name__ == '__main__':\n",
" \n",
"# Importable Literate Notebooks\n",
"\n",
" \n",
" import readme\n",
" \n",
"with the following tests \n",
"\n",
" assert readme.__file__ == 'readme.ipynb'\n",
" assert readme.bar is bar\n",
" bar = 3.14\n",
" assert readme.bar is not bar\n",
" \n",
"\n",
"---\n",
"\n",
"_`literacy;` makes it possible to import any notebook._\n",
"\n",
"---"
]
},
{
"cell_type": "code",
"execution_count": 7,
"metadata": {},
"outputs": [
{
"data": {
"text/markdown": [
"## Marking up functions\n",
"\n",
"It is possible to `def \\`ine a function named `foo\\` with a body composed below,\n",
"\n",
"Our function __foo__ has parameters __x__ and __y__\n",
"\n",
" (x=42, y=10):\n",
" \"\"\"Make sure to have a docstring\"\"\"\n",
"with the ability to interpose markdown into the code, and\n",
" \n",
" return x*y"
],
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"## Marking up functions\n",
"\n",
"It is possible to `def \\`ine a function named `foo\\` with a body composed below,\n",
"\n",
"Our function __foo__ has parameters __x__ and __y__\n",
"\n",
" (x=42, y=10):\n",
" \"\"\"Make sure to have a docstring\"\"\"\n",
"with the ability to interpose markdown into the code, and\n",
" \n",
" return x*y"
]
},
{
"cell_type": "code",
"execution_count": 8,
"metadata": {},
"outputs": [
{
"data": {
"text/markdown": [
"# Inspect Source\n",
" \n",
"In the interactive mode `__name__ == '__main__' and 'In' in globals() and \\` exists to store the prior code executed.\n",
"\n",
" print(\"\"\"The source code for the previous cell is:\\n\\n\"\"\", In[-2])"
],
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
},
{
"name": "stdout",
"output_type": "stream",
"text": [
"The source code for the previous cell is:\n",
"\n",
" def foo(x=42, y=10):\n",
" \"\"\"Make sure to have a docstring\"\"\"\n",
"\n",
" return x*y\n"
]
}
],
"source": [
"# Inspect Source\n",
" \n",
"In the interactive mode `__name__ == '__main__' and 'In' in globals() and \\` exists to store the prior code executed.\n",
"\n",
" print(\"\"\"The source code for the previous cell is:\\n\\n\"\"\", In[-2])"
]
},
{
"cell_type": "code",
"execution_count": 9,
"metadata": {},
"outputs": [
{
"data": {
"text/markdown": [
"# Nbconvert\n",
"\n",
"`literacy;` complies with the __nbconvert__ converters. A successful use of literate programming will require the input cells to be suppressed\n",
"\n",
"```%%bash\n",
"jupyter nbconvert --to markdown --TemplateExporter.exclude_input=True readme.ipynb\n",
"```\n",
"\n",
"add the --execute flag to execute the notebook before it is converted."
],
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
},
{
"name": "stderr",
"output_type": "stream",
"text": [
"[NbConvertApp] Converting notebook readme.ipynb to markdown\n",
"[NbConvertApp] Writing 2381 bytes to readme.md\n"
]
}
],
"source": [
"# Nbconvert\n",
"\n",
"`literacy;` complies with the __nbconvert__ converters. A successful use of literate programming will require the input cells to be suppressed\n",
"\n",
"```%%bash\n",
"jupyter nbconvert --to markdown --TemplateExporter.exclude_input=True readme.ipynb\n",
"```\n",
"\n",
"add the --execute flag to execute the notebook before it is converted."
]
},
{
"cell_type": "code",
"execution_count": 10,
"metadata": {},
"outputs": [
{
"data": {
"text/markdown": [
" %%markdown\n",
" # This is literate source"
],
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
},
{
"data": {
"text/markdown": [
"# This is literate source"
],
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
" %%markdown\n",
" # This is literate source"
]
}
],
"metadata": {
"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.5.4"
}
},
"nbformat": 4,
"nbformat_minor": 2
}