This Node.js module exports a function getRpcSpecFromCells that generates REST API documentation from Jupyter notebooks by grouping permissions, iterating over cells, and creating method objects. It returns an object containing documentation details such as title, name, description, and parameters.

Run example

npm run import -- "convert notebook to open api"

convert notebook to open api

var path = require('path')
var package = require('../package.json')
var importer = require('../Core')
var getRpcFromSpec = importer.import("get rpc from spec")
var getPermissions = importer.import("rpc permissions")
var groupPermissions = importer.import("test rpc permissions")
var getParameters = importer.import("get parameters")

// TODO: move this to patterns utility
function getTail(path, ctx) {
    var cur = path.split('.')[0]
    if(!cur) return ctx
    if(typeof ctx[cur] === 'undefined') ctx[cur] = {}
    return getTail(path.split('.').slice(1).join('.'), ctx[cur])
}

function getPathId(cell) {
    return path
        .relative('../', cell.filename)
        .replace(/\.ipynb|\s+/ig, '')
        .replace(/[^a-z0-9_\/]/ig, '')
        .replace(/\//ig, '.resources.')
        .toLowerCase()
}

function getRpcSpecFromCells(search) {
    var functions = groupPermissions(['Function', 'Available'], search)
    var resources = Object.keys(functions).reduce((obj, f) => {
        var cell = importer.interpret(f)
        var path = getPathId(cell)
        cell.params = getParameters(cell.code)
        var fn = cell.params[0]
        var tail = getTail(`${path}`, obj)
        if(typeof tail.methods === 'undefined') tail.methods = {}
        tail.methods[fn] = {
            description: cell.markdown,
            scopes: functions[f],
            id: `${package.name}.${path}.${fn}`,
            httpMethod: 'GET',
            path: `?function=${cell.questions[0]}`,
            parameters: cell.params.slice(1).reduce((o, p) => (o[p] = {
                type: 'string',
                location: 'query',
                required: true,
                description: ''
            }, o), {})
        }
        return obj
    }, {})
    return {
        title: 'Jupyter Ops',
        name: package.name,
        description: package.description,
        protocol: 'rest',
        baseUrl: process.env.FUNCTIONS_URL,
        resources: resources,
        auth: {},
        schemas: {},
        parameters: {}
    }
}

module.exports = getRpcSpecFromCells;

const path = require('path');
const packageJson = require('../package.json');
const { importer } = require('../Core');

const { getRpcFromSpec, getPermissions, groupPermissions, getParameters } = importer;

// Extract the tail of an object path
function getTail(path, ctx, separator = '.') {
  const parts = path.split(separator);
  let current = ctx;
  for (const part of parts) {
    if (!current[part]) current[part] = {};
    current = current[part];
  }
  return current;
}

// Normalize a file path to a unique identifier
function getPathId(cell) {
  return (
    path
     .relative('../', cell.filename)
     .replace(/\.ipynb|\s+/gi, '')
     .replace(/[^a-z0-9_\/]/gi, '')
     .replace(/\//gi, '.resources.')
     .toLowerCase()
  );
}

// Generate an RPC spec from a list of cells
function getRpcSpecFromCells(search) {
  const functions = groupPermissions(['Function', 'Available'], search);
  const resources = Object.keys(functions).reduce((acc, f) => {
    const cell = importer.interpret(f);
    const path = getPathId(cell);
    const params = getParameters(cell.code);
    const { description, scopes } = functions[f];

    const tail = getTail(path, acc);
    if (!tail.methods) tail.methods = {};
    tail.methods[params[0]] = {
      description: cell.markdown,
      scopes,
      id: `${packageJson.name}.${path}.${params[0]}`,
      httpMethod: 'GET',
      path: `?function=${cell.questions[0]}`,
      parameters: params
       .slice(1)
       .reduce((acc, p) => ({...acc, [p]: { type:'string', location: 'query', required: true, description: '' } }), {}),
    };

    return acc;
  }, {});

  return {
    title: 'Jupyter Ops',
    name: packageJson.name,
    description: packageJson.description,
    protocol:'rest',
    baseUrl: process.env.FUNCTIONS_URL,
    resources,
    auth: {},
    schemas: {},
    parameters: {},
  };
}

module.exports = getRpcSpecFromCells;

Short Breakdown of the Code

This is a Node.js module that exports a function getRpcSpecFromCells to generate REST API documentation from Jupyter notebooks. Here's a high-level overview of the code:

Dependencies and Imports

• The module requires several dependencies, including:
  • path for working with file paths
  • package.json for accessing project metadata
  • Core module for importing other functions
• It imports several functions from other modules:
  • getRpcFromSpec
  • getPermissions
  • groupPermissions
  • getParameters

Helper Functions

• getTail: a recursive function that splits a string into a path and returns the last part as an object
• getPathId: a function that takes a cell object and returns a unique ID for the cell as a string
• getRpcSpecFromCells: the main function that generates REST API documentation from Jupyter notebooks

getRpcSpecFromCells Function

• This function takes a search string as input and returns an object containing REST API documentation
• It:
  1. Groups permissions by function and resource
  2. Iterates over the cells in the search string
  3. For each cell, it:
     • Extracts the function name and parameters
     • Creates a method object with description, scopes, ID, HTTP method, path, and parameters
     • Adds the method to the documentation object
• It returns an object with title, name, description, protocol, base URL, resources, auth, schemas, and parameters

Export

• The module exports the getRpcSpecFromCells function