grassrootseconomics/openethereum
8
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Extended JS interface -> Markdown generator (#4275)

Browse Source 
* Extended Markdown generator

* Fix linter errors

* Review fixes
This commit is contained in:
Maciej Hirsz
2017-01-24 16:05:21 +01:00
committed by Jaco Greeff
parent 9d0278e0f8
commit a30a108ac9
7 changed files with 401 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
js/src/jsonrpc/README.md
View File

@@ -12,9 +12,10 @@ JSON file of all ethereum's rpc methods supported by parity
0. Branch
0. Add the missing interfaces only into `src/interfaces/*.js`
0. Parameters (array) & Returns take objects of type
- `{ type: [Array|Boolean|Object|String|...], desc: 'some description' }`
- `{ type: [Array|Boolean|Object|String|...], desc: 'some description', example: 100|'0xff'|{ ... } }`
- Types are built-in JS types or those defined in `src/types.js` (e.g. `BlockNumber`, `Quantity`, etc.)
- If a formatter is required, add it as `format: 'string-type'`
0. Run the lint & tests, `npm run lint && npm run testOnce`
0. Generate via `npm run build` which outputs `index.js`, `index.json` & `interfaces.md` (Only required until Travis is fully in-place)
0. Check-in and make a PR
0. Run the lint & tests, `npm run lint && npm run test`
0. Generate via `npm run build` which outputs `index.js` & `index.json`.
0. (optional) Generate docs via `npm run build:markdown` which outputs `md` files to `./docs`.
0. Check-in and make a PR.

67
js/src/jsonrpc/generator/build-json.js
View File

@@ -1,67 +0,0 @@
// Copyright 2015, 2016 Parity Technologies (UK) Ltd.
// This file is part of Parity.
// Parity is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
// Parity is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
// You should have received a copy of the GNU General Public License
// along with Parity. If not, see <http://www.gnu.org/licenses/>.
import fs from 'fs';
import path from 'path';
import interfaces from '../';
const INDEX_JSON = path.join(__dirname, '../../release/index.json');
const methods = [];
function formatDescription (obj) {
const optional = obj.optional ? '(optional) ' : '';
const defaults = obj.default ? `(default: ${obj.default}) ` : '';
return `${obj.type.name} - ${optional}${defaults}${obj.desc}`;
}
function formatType (obj) {
if (obj.type === Object && obj.details) {
const formatted = {};
Object.keys(obj.details).sort().forEach((key) => {
formatted[key] = formatType(obj.details[key]);
});
return {
desc: formatDescription(obj),
details: formatted
};
} else if (obj.type && obj.type.name) {
return formatDescription(obj);
}
return obj;
}
Object.keys(interfaces).sort().forEach((group) => {
Object.keys(interfaces[group]).sort().forEach((name) => {
const method = interfaces[group][name];
const deprecated = method.deprecated ? ' (Deprecated and not supported, to be removed in a future version)' : '';
methods.push({
name: `${group}_${name}`,
desc: `${method.desc}${deprecated}`,
params: method.params.map(formatType),
returns: formatType(method.returns),
inputFormatters: method.params.map((param) => param.format || null),
outputFormatter: method.returns.format || null
});
});
});
fs.writeFileSync(INDEX_JSON, JSON.stringify({ methods: methods }, null, 2), 'utf8');

69
js/src/jsonrpc/generator/build-markdown.js
View File

@@ -1,69 +0,0 @@
// Copyright 2015, 2016 Parity Technologies (UK) Ltd.
// This file is part of Parity.
// Parity is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
// Parity is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
// You should have received a copy of the GNU General Public License
// along with Parity. If not, see <http://www.gnu.org/licenses/>.
import fs from 'fs';
import path from 'path';
import interfaces from '../';
const MARKDOWN = path.join(__dirname, '../../release/interfaces.md');
let preamble = '# interfaces\n';
let markdown = '';
function formatDescription (obj, prefix = '', indent = '') {
const optional = obj.optional ? '(optional) ' : '';
const defaults = obj.default ? `(default: ${obj.default}) ` : '';
return `${indent}- ${prefix}\`${obj.type.name}\` - ${optional}${defaults}${obj.desc}`;
}
function formatType (obj) {
if (obj.type === Object && obj.details) {
const sub = Object.keys(obj.details).sort().map((key) => {
return formatDescription(obj.details[key], `\`${key}\`/`, ' ');
}).join('\n');
return `${formatDescription(obj)}\n${sub}`;
} else if (obj.type && obj.type.name) {
return formatDescription(obj);
}
return obj;
}
Object.keys(interfaces).sort().forEach((group) => {
let content = '';
preamble = `${preamble}\n- [${group}](#${group})`;
markdown = `${markdown}\n## ${group}\n`;
Object.keys(interfaces[group]).sort().forEach((iname) => {
const method = interfaces[group][iname];
const name = `${group}_${iname}`;
const deprecated = method.deprecated ? ' (Deprecated and not supported, to be removed in a future version)' : '';
const desc = `${method.desc}${deprecated}`;
const params = method.params.map(formatType).join('\n');
const returns = formatType(method.returns);
markdown = `${markdown}\n- [${name}](#${name})`;
content = `${content}### ${name}\n\n${desc}\n\n#### parameters\n\n${params || 'none'}\n\n#### returns\n\n${returns || 'none'}\n\n`;
});
markdown = `${markdown}\n\n${content}`;
});
fs.writeFileSync(MARKDOWN, `${preamble}\n\n${markdown}`, 'utf8');

62
js/src/jsonrpc/helpers.js Normal file
View File

@@ -0,0 +1,62 @@
// Copyright 2015, 2016 Parity Technologies (UK) Ltd.
// This file is part of Parity.
// Parity is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
// Parity is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
// You should have received a copy of the GNU General Public License
// along with Parity. If not, see <http://www.gnu.org/licenses/>.
// Placeholders for objects with undefined fields, will show up in docs as `{ ... }`
export const DUMMY = '$DUMMY$';
// Enrich the API spec by additional markdown-formatted preamble
export function withPreamble (preamble, spec) {
Object.defineProperty(spec, '_preamble', {
value: preamble.trim(),
enumerable: false
});
return spec;
}
// Enrich any example value with a comment to print in the docs
export function withComment (example, comment) {
const constructor = example == null ? null : example.constructor;
if (constructor === Object || constructor === Array) {
Object.defineProperty(example, '_comment', {
value: comment,
enumerable: false
});
return example;
}
// Convert primitives
return new PrimitiveWithComment(example, comment);
}
// Turn a decimal number into a hexadecimal string with comment to it's original value
export function fromDecimal (decimal) {
return withComment(`0x${decimal.toString(16)}`, decimal.toString());
}
// Internal helper
class PrimitiveWithComment {
constructor (primitive, comment) {
this._value = primitive;
this._comment = comment;
}
toJSON () {
return this._value;
}
}