hypatia

Converting JavaScript doctrings (in jsdoc AST format) to ijavascript Jupyter Notebooks

Background

Having interactive documentation in the form of Jupyter notebooks is awesome. So is having accurate and up to date code-level documentation in the form of comments. Wouldn't it be cool if you had a tool that transliterated the latter into the former, giving you fully interactive Jupyter notebook versions of your docstring comments?

In other words, Hypatia turns this:

/**
 * @description
 * Log implements a G-Set CRDT and adds ordering
 * Create a new Log instance
 *
 * From:
 * "A comprehensive study of Convergent and Commutative Replicated Data Types"
 * https://hal.inria.fr/inria-00555588
 *
 * @constructor
 *
 * @example
 * const IPFS = require("ipfs")
 * const Log = require("../src/log")
 * const { AccessController, IdentityProvider } = require("../src/log")
 * const Keystore = require('orbit-db-keystore')
 * const Entry = require("../src/entry")
 * const Clock = require('../src/lamport-clock')
 *
 * const accessController = new AccessController()
 * const ipfs = new IPFS();
 * const keystore = Keystore.create("../test/fixtures/keys")
 * const identitySignerFn = async (id, data) => {
 *   const key = await keystore.getKey(id)
 *   return keystore.sign(key, data)
 * }
 *
 * (async () => {
 *   var identity = await IdentityProvider.createIdentity(keystore, 'username', identitySignerFn)
 *   var log = new Log(ipfs, accessController, identity)
 *
 *   // console.log(Object.keys(log))
 * })()
 *
 *
 * @param  {IPFS}           [ipfs]          An IPFS instance
 * @param  {Object}         [access]        AccessController (./default-access-controller)
 * @param  {Object}         [identity]      Identity (https://github.com/orbitdb/orbit-db-identity-provider/blob/master/src/identity.js)
 * @param  {String}         [logId]         ID of the log
 * @param  {Array<Entry>}   [entries]       An Array of Entries from which to create the log
 * @param  {Array<Entry>}   [heads]         Set the heads of the log
 * @param  {Clock}          [clock]         Set the clock of the log
 * @return {Log}                            Log
 */

into this:

Hypatia is built with native ReasonML and was created to manage the documentation in the orbitdb repositories.

Installation

Prerequisites: esy and pesy

Hypatia currently requires the esy and pesy tools to build and run.

npm install -g esy pesy

Installation Steps

npm install -g hypatia

Then, the binary will be available at hypatia.exe. Move it where you want!

Usage

First, create the jsdoc AST file.

jsdoc -X ./path/to/js/**/**.js > jsdoc-ast.json

Then, use hypatia.exe to generate the ipynb

$ hypatia.exe

Hypatia - jsdoc to ijavascript
Usage: hypatia.exe [input_file] [output_file]
 - input_file: jsondoc output .json file
 - output_file: jupyter notebook .ipynb file

$ hypatia.exe jsdoc-ast.json API.ipynb

Contributing

Feel free to ask questions via GitHub issues. PRs are welcome.

To build the executable locally, follow these steps:

git clone https://github.com/aphelionz/hypatia.git
esy install
esy pesy
esy build

You can then run the example via npm run example or the executable via esy x hypatia.exe.

Then, if you would like, use esy release to build the npm package.

License

MIT © 2018 Mark Henderson