{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "## Notebook generation" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "This module contains the scripts and API to auto-generate or update a documentation notebook skeleton from a fastai module (e.g. - fastai.*) or existing documentation file (e.g. - docs_src/*.ipynb). It is not expected you'd use this skeleton as your final docs - you should add markdown, examples, etc to it. The skeleton just has a minimal list of exported symbols.\n", "\n", "[`tools/build-docs`](https://github.com/fastai/fastai/blob/master/tools/build-docs) contains a command line tool that transforms a given module into a notebook skeleton. It's essentially a wrapper around [`gen_notebooks.update_notebooks`](/gen_doc.gen_notebooks.html#update_notebooks). For usage around the command line tool, please follow instructions at [`gen_doc_main#updating-notebooks`](/gen_doc_main.html#updating-notebooks).\n", "\n", "Alternatively, you can access the same functionality through the module API, documented below.\n", "\n", "**Important note:** The notebooks automatically generated or updated need to be trusted before you can see the results in the output cells. To trust a notebook, click on File, then Trust notebook.\n", "\n", "This module also contains the scripts and API to convert the documentation notebooks into HTML, which is the format used for the final documentation site." ] }, { "cell_type": "code", "execution_count": null, "metadata": { "hide_input": true }, "outputs": [], "source": [ "from fastai import gen_doc\n", "from fastai.gen_doc import nbdoc\n", "from fastai.gen_doc.nbdoc import *\n", "from fastai.gen_doc.gen_notebooks import *" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Installation" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "This package requires:\n", "- [nbconvert](https://github.com/jupyter/nbconvert): conda install nbconvert\n", "- [nb_extensions](https://github.com/ipython-contrib/jupyter_contrib_nbextensions): conda install -c conda-forge jupyter_contrib_nbextensions" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Once nbextensions is installed, your home page of jupyter notebook will look like this:\n", "\n", "![Homepage with nbextension](imgs/nbext.png)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Click on the Nbextensions tab then make sure the hide inputs extension is activated:\n", "\n", "![Activate hidden input](imgs/hide_input.png)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "As its name suggests, this will allow you to hide input cells and only show their results.\n", "\n", "There is also the `Hide Input all` extension, but don't use it, since it toggles all inputs on/off and once executed it'll be very difficult to restore the notebook to its original state where some inputs are supposed to be hidden and some are not." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Convert modules into notebook skeleton" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The first (optional) step is to create a notebook \"skeleton\" - i.e. a notebook containing all the classes, methods, functions, and other symbols you wish to document. You can create this manually if you prefer, however using the automatic approach can save you some time and ensure you don't miss anything. \n", "\n", "For the initial skeleton, use [`create_module_page`](/gen_doc.gen_notebooks.html#create_module_page), which creates a new module from scratch. To update it later with any newly-added symbols, use [`update_module_page`](/gen_doc.gen_notebooks.html#update_module_page)." ] }, { "cell_type": "code", "execution_count": null, "metadata": { "hide_input": true }, "outputs": [ { "data": { "text/markdown": [ "

create_module_page[source]

\n", "\n", "> create_module_page(**`mod`**, **`dest_path`**, **`force`**=***`False`***)\n", "\n", "Create the documentation notebook for module `mod_name` in path `dest_path` \n", "\n", "- *mod*: the module\n", "- *dest_path*: the folder in which to generate the notebook\n", "- *force*: if False, will raise an exception if the notebook is already present " ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "show_doc(create_module_page, arg_comments={\n", " 'mod': 'the module',\n", " 'dest_path': 'the folder in which to generate the notebook',\n", " 'force': 'if False, will raise an exception if the notebook is already present'})" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Equivalent [CLI](/gen_doc_main.html#creating-a-new-documentation-notebook-from-existing-module):\n", "```bash\n", "tools/build-docs fastai.subpackage.module\n", "```" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "hide_input": true }, "outputs": [ { "data": { "text/markdown": [ "\n", "\n", "> link_nb(**`nb_path`**)" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "show_doc(link_nb)" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "hide_input": true }, "outputs": [ { "data": { "text/markdown": [ "

update_module_page[source]

\n", "\n", "> update_module_page(**`mod`**, **`dest_path`**=***`'.'`***)\n", "\n", "Update the documentation notebook of a given module. \n", "\n", "- *mod*: the module\n", "- *dest_path*: the folder in which to generate the notebook " ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "show_doc(update_module_page, arg_comments={\n", " 'mod': 'the module',\n", " 'dest_path': 'the folder in which to generate the notebook'})" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "All the cells added by a user are conserved, only the cells of new symbols (aka that weren't documented before) will be inserted at the end. You can then move them to wherever you like in the notebook. For instance, to update this module's documentation, simply run:\n", "\n", "```\n", "update_module_page(gen_doc.gen_notebooks, '.')\n", "```\n", "\n", "You can also generate and update *all* modules in a package using [`update_notebooks`](/gen_doc.gen_notebooks.html#update_notebooks)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Equivalent [CLI](/gen_doc_main.html#updating-an-existing-functionclass):\n", "```bash\n", "tools/build-docs docs_src/gen_doc.gen_notebooks.ipynb\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Updating module metadata" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Jekyll pulls the documentation title, summary, and keywords from the metadata of each notebook. \n", "Notebook metadata structure looks like this: `'metadata': { 'jekyll': {...} }` \n", "\n", "To update metadata of these notebooks, run `generate_missing_metadata('.')`. Then open the notebook `jekyll_metadata.ipynb` to change the metadata." ] }, { "cell_type": "code", "execution_count": null, "metadata": { "hide_input": true }, "outputs": [ { "data": { "text/markdown": [ "

generate_missing_metadata[source]

\n", "\n", "> generate_missing_metadata(**`dest_file`**)" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "show_doc(generate_missing_metadata)" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "hide_input": true }, "outputs": [ { "data": { "text/markdown": [ "

update_nb_metadata[source]

\n", "\n", "> update_nb_metadata(**`nb_path`**=***`None`***, **`title`**=***`None`***, **`summary`**=***`None`***, **`keywords`**=***`'fastai'`***, **`overwrite`**=***`True`***, **\\*\\*`kwargs`**)\n", "\n", "Creates jekyll metadata for given notebook path. " ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "show_doc(update_nb_metadata)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Updating all module docs" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "hide_input": true }, "outputs": [ { "data": { "text/markdown": [ "

update_notebooks[source]

\n", "\n", "> update_notebooks(**`source_path`**, **`dest_path`**=***`None`***, **`update_html`**=***`True`***, **`document_new_fns`**=***`False`***, **`update_nb_links`**=***`True`***, **`html_path`**=***`None`***, **`force`**=***`False`***)\n", "\n", "`source_path` can be a directory or a file. Assume all modules reside in the fastai directory. " ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "show_doc(update_notebooks)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "As a convenience method, this can update all notebooks. This snippet does the whole lot for you:\n", "\n", "```python\n", "update_notebooks('docs_src', update_html=False, update_nb=True):\n", "```\n", "\n", "This will update all ipynb documentation notebooks specified under source_path" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Add documentation" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The automatically generated module will only contain the table of contents and the doc string of the functions and classes in your module (or the ones you picked with \\_\\_all\\_\\_). You should add more prose to them in markdown cells, or examples of uses inside the notebook." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "At any time, if you don't want the input of a code cell to figure in the final result, you can use the little button in your tool bar to hide it.\n", "\n", "![Button to hide an input](imgs/button_hide.png)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The same button can show you the hidden input from a cell. This used in conjunction with the helper functions from [nbdoc](gen_doc.nbdoc.ipynb) should allow you to easily add any content you need." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Convert notebook to html" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Once you're finished, don't forget to properly save your notebook, then you can either convert all the notebooks together with the script:\n", "```\n", "python -m convert2html dir\n", "```\n", "- **dir** is the directory where all your notebooks are stored.\n", "\n", "If you prefer to do this in a notebook, you can simply type:\n", "\n", "```python\n", "from fastai.gen_doc.convert2html import convert_nb\n", "convert_nb('gen_doc.gen_notebooks.ipynb', '../docs')\n", "```\n", "\n", "For more information see the [documentation of convert2html](/gen_doc.convert2html.html)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Undocumented Methods - Methods moved below this line will intentionally be hidden" ] } ], "metadata": { "jekyll": { "keywords": "fastai", "summary": "Generation of documentation notebook skeletons from python module", "title": "gen_doc.gen_notebooks" }, "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" } }, "nbformat": 4, "nbformat_minor": 2 }