Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/aphelionz/hypatia
Convert JavaScript doctrings (in jsdoc AST format) to ijavascript Jupyter Notebooks
https://github.com/aphelionz/hypatia
hypatia ijavascript ijavascript-jupyter-notebooks jsdoc jupyter jupyter-notebook jupyter-notebooks reasonml
Last synced: about 1 month ago
JSON representation
Convert JavaScript doctrings (in jsdoc AST format) to ijavascript Jupyter Notebooks
- Host: GitHub
- URL: https://github.com/aphelionz/hypatia
- Owner: aphelionz
- License: mit
- Created: 2018-11-26T18:19:55.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2019-03-05T20:05:28.000Z (over 5 years ago)
- Last Synced: 2024-06-13T00:56:43.032Z (5 months ago)
- Topics: hypatia, ijavascript, ijavascript-jupyter-notebooks, jsdoc, jupyter, jupyter-notebook, jupyter-notebooks, reasonml
- Language: OCaml
- Homepage:
- Size: 5.78 MB
- Stars: 12
- Watchers: 5
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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} [entries] An Array of Entries from which to create the log
* @param {Array} [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`](https://github.com/orbitdb) repositories.
## Installation
### Prerequisites: [`esy`](https://github.com/esy/esy) and [`pesy`](https://github.com/jordwalke/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](LICENSE) © 2018 Mark Henderson