class: center, middle # Interactive Documentation --- # About me * API writer * Developer * German * Jack-of-all-trades * **Unicorn** * working for IBM - Cloud Data Services @KimStebel [www.kimstebel.com](https://www.kimstebel.com/) --- # Ask questions! Complain! --- # Agenda 1. What and why? 2. Swagger 3. Notebooks --- # What is interactive documentation? Users can... * Make requests against the API * Execute code snippets ... on the documetation site. --- # Why interactive documentation? --- # Code snippets actually work! --- # Developers contribute code snippets --- # Learning by doing --- # People are impatient Get from "Hey, this seems interesting" to "it works!" in 10 seconds --- # Drive adoption --- # Swagger * Yes, great for reference documentation of REST APIs But... * Not all APIs are RESTful (nor should they be) * Client library examples? * Not meant for tutorials --- # Jupyter Notebooks (ipython notebooks) The [Jupyter Notebook](https://jupyter.org/) is an open source web application that allows you to create and share documents that contain live code, equations, visualizations. * Supports over 40 programming languages * Code can produce output such as images, videos, LaTeX, and JavaScript --- # Jupyter notebooks ![jupyter screenshot](screenshot.png) --- # Jupyter Notebooks - but... * Developed with academia and education in mind * Notebook servers are single user. Each user needs their own notebook server instance * Thus, usually run locally or behind a login (e.g. Coursera). * How do we use notebooks in documentation? Requirements: No installation, no login --- # (ab)using Jupyter for documentation * tmpnb: Temporary notebook server * Replace the frontend: Thebe, or use the API... --- # tmpnb - Temporary Notebook Server * [tmpnb](https://github.com/jupyter/tmpnb) manages a pool of docker containers and assigns one to each user * used to provide temporary notebooks * used at user groups, meetups, and workshops to provide temporary access to a full system without any installation * runs https://try.jupyter.org/. --- # tmpnb - Temporary Notebook Server ![tmpnb architecture](tmpnb.png) --- # tmpnb - based on Docker * Docker! Yay! * You can create your own Docker image for the Jupyter container * Base images available from Jupyter * You can add language kernels, libraries, data sets... --- # Thebe - An alternative Notebook UI Tmpnb solves the multiuser problem, but it still has the same clunky UI. [Thebe](https://github.com/oreillymedia/thebe) is a Javascript library that uses tmpnb as a backend for code execution. It can be integrated into any website like this: ``` $(function(){ new Thebe({ selector: "code.python", kernel_name: "python2", url: "http://some.tmpnb.server.com:8000" }); }); ``` Any `
` tag will have a run button added. ```
import cloudant ...
``` --- # Questions?