Last active
September 6, 2016 04:02
-
-
Save jakevdp/7e8652704661b449d78ddc6e58450c4f to your computer and use it in GitHub Desktop.
First attempt at auto-doc for altair API
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
{ | |
"cells": [ | |
{ | |
"cell_type": "code", | |
"execution_count": 1, | |
"metadata": { | |
"collapsed": false | |
}, | |
"outputs": [], | |
"source": [ | |
"import altair\n", | |
"import traitlets" | |
] | |
}, | |
{ | |
"cell_type": "code", | |
"execution_count": 2, | |
"metadata": { | |
"collapsed": true | |
}, | |
"outputs": [], | |
"source": [ | |
"import jinja2\n", | |
"\n", | |
"TEMPLATE = jinja2.Template(\"\"\"### {{ obj.name }}\n", | |
"\n", | |
"*{{ obj.description }}*\n", | |
"\n", | |
"| Trait | type | description |\n", | |
"|-------|------|-------------|\n", | |
"{% for trait in obj.traits -%}\n", | |
"| **{{ trait.name }}**| *{{ trait.type }}* | {{ trait.help }} |\n", | |
"{% endfor %}\n", | |
"\"\"\")" | |
] | |
}, | |
{ | |
"cell_type": "code", | |
"execution_count": 3, | |
"metadata": { | |
"collapsed": false | |
}, | |
"outputs": [], | |
"source": [ | |
"import types\n", | |
"import traitlets\n", | |
" \n", | |
"def _get_trait_info(name, trait):\n", | |
" type_ = trait.info()\n", | |
" help_ = trait.help\n", | |
" if isinstance(trait, traitlets.Instance):\n", | |
" if issubclass(trait.klass, traitlets.HasTraits):\n", | |
" type_ = '[{0}](#{0})'.format(trait.klass.__name__)\n", | |
" if isinstance(trait, traitlets.Enum):\n", | |
" values = trait.values\n", | |
" if all(isinstance(val, str) for val in values):\n", | |
" type_ = 'a unicode string'\n", | |
" help_ += ' One of {0}.'.format(values)\n", | |
" return {'name': name, 'help': help_ or '--', 'type': type_ or '--'}\n", | |
"\n", | |
"\n", | |
"def _get_object_info(obj):\n", | |
" D = {}\n", | |
" D['name'] = obj.__name__\n", | |
" if obj.__doc__:\n", | |
" D['description'] = obj.__doc__.splitlines()[0]\n", | |
" else:\n", | |
" D['description'] = obj.__name__\n", | |
" \n", | |
" D['traits'] = [_get_trait_info(name, trait)\n", | |
" for name, trait in sorted(obj.class_traits().items())]\n", | |
" \n", | |
" return D\n", | |
"\n", | |
"\n", | |
"def altair_nbdoc(obj):\n", | |
" if obj is altair:\n", | |
" for sub_obj in dir(obj):\n", | |
" if sub_obj.startswith('_'):\n", | |
" continue\n", | |
" yield from altair_nbdoc(getattr(obj, sub_obj))\n", | |
" elif isinstance(obj, type) and issubclass(obj, traitlets.HasTraits):\n", | |
" yield _get_object_info(obj)" | |
] | |
}, | |
{ | |
"cell_type": "code", | |
"execution_count": 4, | |
"metadata": { | |
"collapsed": true | |
}, | |
"outputs": [], | |
"source": [ | |
"from itertools import tee, filterfalse\n", | |
"\n", | |
"def partition(iterable, predicate):\n", | |
" true, false = tee(iterable, 2)\n", | |
" return filter(predicate, true), filterfalse(predicate, false)" | |
] | |
}, | |
{ | |
"cell_type": "code", | |
"execution_count": 5, | |
"metadata": { | |
"collapsed": false | |
}, | |
"outputs": [], | |
"source": [ | |
"from itertools import filterfalse\n", | |
"\n", | |
"from ipykernel import kernelspec as ks\n", | |
"import nbformat\n", | |
"from nbformat.v4.nbbase import new_markdown_cell, new_code_cell, new_notebook\n", | |
"from operator import itemgetter\n", | |
"\n", | |
"kernelspec = ks.get_kernel_dict()\n", | |
"kernelspec['name'] = ks.KERNEL_NAME\n", | |
"kernelspec.pop('argv');\n", | |
"\n", | |
"toplevel = lambda obj: 'Chart' in obj['name']\n", | |
"content = sorted(altair_nbdoc(altair), key=itemgetter('name'))\n", | |
"\n", | |
"cells = [new_markdown_cell(source=(\n", | |
" '# Altair API Documentation\\n\\n'\n", | |
" '*This is auto-generated from '\n", | |
" '[Altair_DocGen.ipynb](Altair_DocGen.ipynb)*'))]\n", | |
"cells.append(new_markdown_cell(source='## Top-Level Objects'))\n", | |
"cells.extend([new_markdown_cell(source=TEMPLATE.render(obj=obj))\n", | |
" for obj in filter(toplevel, content)])\n", | |
"\n", | |
"cells.append(new_markdown_cell(source='## Other Objects'))\n", | |
"cells.extend([new_markdown_cell(source=TEMPLATE.render(obj=obj))\n", | |
" for obj in filterfalse(toplevel, content)])\n", | |
"\n", | |
"notebook = new_notebook(cells=cells,\n", | |
" metadata={'language': 'python',\n", | |
" 'kernelspec': kernelspec})\n", | |
"nbformat.write(notebook, 'AltairAPI.ipynb')" | |
] | |
} | |
], | |
"metadata": { | |
"anaconda-cloud": {}, | |
"kernelspec": { | |
"display_name": "Python 3.5", | |
"language": "", | |
"name": "python3.5" | |
}, | |
"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.1" | |
}, | |
"widgets": { | |
"state": {}, | |
"version": "1.0.0" | |
} | |
}, | |
"nbformat": 4, | |
"nbformat_minor": 0 | |
} |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment