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