{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Discussion" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Markdown for literate programming" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Alternative source files" ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [ { "data": { "text/markdown": [ " import pidgy, pandas, types, builtins, pathlib" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ " import pidgy, pandas, types, builtins, pathlib" ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [ { "data": { "text/markdown": [ "pidgy is a literate program and it uses a mix of files for its source. Until, the tangle step\n", "of literate programming we have to rely on available files with avaiable improters,\n", "afterwards markdown is used as source.\n", "\n", "\n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", " \n", "
.md.ipynb.py
extensions732
\n", " \n", " file_counts = pandas.Series({k:pathlib.Path(v.__file__).suffix for k,v in vars(pidgy).items() if isinstance(v, types.ModuleType) and v is not builtins}).value_counts().to_frame('extensions').T" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "pidgy is a literate program and it uses a mix of files for its source. Until, the tangle step\n", "of literate programming we have to rely on available files with avaiable improters,\n", "afterwards markdown is used as source.\n", "\n", "{{file_counts.to_html()}}\n", " \n", " file_counts = pandas.Series({k:pathlib.Path(v.__file__).suffix for k,v in vars(pidgy).items() if isinstance(v, types.ModuleType) and v is not builtins}).value_counts().to_frame('extensions').T" ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [ { "data": { "text/markdown": [ "## Shebangs\n", "\n", "Perhaps one of the more damning shortcomings of the notebook is that it is no a script, and requires specialized software to execute.\n", "\n", "`pidgy` markdown documents can begin with a shebang line that defines how the\n", "script should be executed.\n", "\n", "```bash\n", "#!/usr/bin/env python -m pidgy run file.md\n", "```\n", "\n", "When the shebang is included the markdown file can be executed at the command line with a preceeding period.\n", "\n", "```bash\n", "./file.md\n", "```" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "## Shebangs\n", "\n", "Perhaps one of the more damning shortcomings of the notebook is that it is no a script, and requires specialized software to execute.\n", "\n", "`pidgy` markdown documents can begin with a shebang line that defines how the\n", "script should be executed.\n", "\n", "```bash\n", "#!/usr/bin/env python -m pidgy run file.md\n", "```\n", "\n", "When the shebang is included the markdown file can be executed at the command line with a preceeding period.\n", "\n", "```bash\n", "./file.md\n", "```" ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [ { "data": { "text/markdown": [ "## Outcomes\n", "\n", "There are numerous outcomes of a source written literate code. With `pidgy`\n", "as an example we can do more than simply tangle and weave a program." ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "## Outcomes\n", "\n", "There are numerous outcomes of a source written literate code. With `pidgy`\n", "as an example we can do more than simply tangle and weave a program." ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [ { "data": { "text/markdown": [ "## Best practices for literate programming in Markdown\n", "\n", " import json\n", "Our core moral commitment is to write literate programs, because:\n", "\n", "> ...; surely nobody wants to admit writing an illiterate program.\n", ">\n", "> > - [Donald Knuth] _[Literate Programming]_\n", "\n", "- Restart and run all or it didn't happen.\n", "\n", " A document should be literate in all readable, reproducible, and reusable\n", " contexts.\n", "\n", "* [Markdown] documents are sufficient for literate progr.\n", "\n", " Markdown documents that translate to python can encode literate programs in a\n", " form that is better if version control systems that the `json` format that\n", " encodes notebooks.\n", "\n", "* All code should compute.\n", "\n", " Testing code in a narrative provides supplemental meaning to the `\"code\"`\n", " signifiers. They provide a test of veracity at least for the computational\n", " literacy.\n", "\n", "* [readme.md] is a good default name for a program.\n", "\n", " Eventually authors will compose [readme.md] documents that act as both the\n", " `\"__init__\"` method and `\"__main__\"` methods of the program.\n", "\n", "* Each document should stand alone,\n", " [despite all possibilities to fall.](http://ing.univaq.it/continenza/Corso%20di%20Disegno%20dell'Architettura%202/TESTI%20D'AUTORE/Paul-klee-Pedagogical-Sketchbook.pdf#page=6)\n", "* Use code, data, and visualization to fill the voids of natural language.\n", "* Find pleasure in writing.\n", "\n", "* When in doubt, abide [Web Content Accessibility Guidelines][wcag] so that\n", " information can be accessed by differently abled audiences.\n", "\n", "* First markdown cell is the docstring \n", " \n", "[wcag]: https://www.w3.org/WAI/standards-guidelines/wcag/\n", "[donald knuth]: #\n", "[literate programming]: #\n", "[markdown]: #\n", "[readme.md]: #" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "## Best practices for literate programming in Markdown\n", "\n", " import json\n", "Our core moral commitment is to write literate programs, because:\n", "\n", "> ...; surely nobody wants to admit writing an illiterate program.\n", ">\n", "> > - [Donald Knuth] _[Literate Programming]_\n", "\n", "- Restart and run all or it didn't happen.\n", "\n", " A document should be literate in all readable, reproducible, and reusable\n", " contexts.\n", "\n", "* [Markdown] documents are sufficient for literate progr.\n", "\n", " Markdown documents that translate to python can encode literate programs in a\n", " form that is better if version control systems that the `json` format that\n", " encodes notebooks.\n", "\n", "* All code should compute.\n", "\n", " Testing code in a narrative provides supplemental meaning to the `\"code\"`\n", " signifiers. They provide a test of veracity at least for the computational\n", " literacy.\n", "\n", "* [readme.md] is a good default name for a program.\n", "\n", " Eventually authors will compose [readme.md] documents that act as both the\n", " `\"__init__\"` method and `\"__main__\"` methods of the program.\n", "\n", "* Each document should stand alone,\n", " [despite all possibilities to fall.](http://ing.univaq.it/continenza/Corso%20di%20Disegno%20dell'Architettura%202/TESTI%20D'AUTORE/Paul-klee-Pedagogical-Sketchbook.pdf#page=6)\n", "* Use code, data, and visualization to fill the voids of natural language.\n", "* Find pleasure in writing.\n", "\n", "* When in doubt, abide [Web Content Accessibility Guidelines][wcag] so that\n", " information can be accessed by differently abled audiences.\n", "\n", "* First markdown cell is the docstring \n", " \n", "[wcag]: https://www.w3.org/WAI/standards-guidelines/wcag/\n", "[donald knuth]: #\n", "[literate programming]: #\n", "[markdown]: #\n", "[readme.md]: #\n" ] }, { "cell_type": "code", "execution_count": 6, "metadata": {}, "outputs": [ { "data": { "text/markdown": [ "## External tools\n", "\n", "`pidgy` works jupyter notebook, jupyterlab, nteract, and colab." ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "## External tools\n", "\n", "`pidgy` works jupyter notebook, jupyterlab, nteract, and colab." ] }, { "cell_type": "code", "execution_count": 7, "metadata": {}, "outputs": [ { "data": { "text/markdown": [ "# Conclusion\n", "\n", "Markdown documents represent a compact form of a literate programming." ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "# Conclusion\n", "\n", "Markdown documents represent a compact form of a literate programming." ] } ], "metadata": { "kernelspec": { "display_name": "pidgy 3", "language": "python", "name": "pidgy" }, "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.7.3" } }, "nbformat": 4, "nbformat_minor": 4 }