Liana Husikyan
1 year ago
committed by
GitHub
commit
e2bb45f0f2
@ -0,0 +1,13 @@ |
||||
{ |
||||
"presets": [ |
||||
[ |
||||
"@nrwl/react/babel", { |
||||
"runtime": "automatic" |
||||
|
||||
} |
||||
] |
||||
], |
||||
"plugins": [ |
||||
|
||||
] |
||||
} |
||||
@ -1 +0,0 @@ |
||||
export * from './app/debugger-api'; |
||||
@ -1,32 +1,87 @@ |
||||
const nxWebpack = require('@nrwl/react/plugins/webpack') |
||||
const { composePlugins, withNx } = require('@nrwl/webpack') |
||||
const webpack = require('webpack') |
||||
const TerserPlugin = require("terser-webpack-plugin") |
||||
const CssMinimizerPlugin = require("css-minimizer-webpack-plugin") |
||||
|
||||
module.exports = config => { |
||||
const nxWebpackConfig = nxWebpack(config) |
||||
|
||||
const webpackConfig = { |
||||
...nxWebpackConfig, |
||||
resolve : { |
||||
...nxWebpackConfig.resolve, |
||||
fallback: { |
||||
...nxWebpackConfig.resolve.fallback, |
||||
// Nx plugins for webpack.
|
||||
module.exports = composePlugins(withNx(), (config) => { |
||||
// Update the webpack config as needed here.
|
||||
// e.g. `config.plugins.push(new MyPlugin())`
|
||||
|
||||
// add fallback for node modules
|
||||
config.resolve.fallback = { |
||||
...config.resolve.fallback, |
||||
"crypto": require.resolve("crypto-browserify"), |
||||
"stream": require.resolve("stream-browserify"), |
||||
"http" : require.resolve("stream-http"), |
||||
"https" : require.resolve("https-browserify"), |
||||
"path" : require.resolve("path-browserify"), |
||||
"path": require.resolve("path-browserify"), |
||||
"http": require.resolve("stream-http"), |
||||
"https": require.resolve("https-browserify"), |
||||
"constants": require.resolve("constants-browserify"), |
||||
"os": false, //require.resolve("os-browserify/browser"),
|
||||
"timers": false, // require.resolve("timers-browserify"),
|
||||
"zlib": require.resolve("browserify-zlib"), |
||||
"fs": false, |
||||
"module": false, |
||||
"fs" : false |
||||
}, |
||||
} |
||||
"tls": false, |
||||
"net": false, |
||||
"readline": false, |
||||
"child_process": false, |
||||
"buffer": require.resolve("buffer/"), |
||||
"vm": require.resolve('vm-browserify'), |
||||
} |
||||
|
||||
if (process.env.NODE_ENV === 'production') { |
||||
return { |
||||
...webpackConfig, |
||||
mode: 'production', |
||||
devtool: 'source-map', |
||||
|
||||
// add externals
|
||||
config.externals = { |
||||
...config.externals, |
||||
solc: 'solc', |
||||
} |
||||
} else { |
||||
return webpackConfig |
||||
|
||||
// add public path
|
||||
config.output.publicPath = '/' |
||||
|
||||
|
||||
|
||||
// add copy & provide plugin
|
||||
config.plugins.push( |
||||
new webpack.ProvidePlugin({ |
||||
Buffer: ['buffer', 'Buffer'], |
||||
url: ['url', 'URL'], |
||||
process: 'process/browser', |
||||
}) |
||||
) |
||||
|
||||
// souce-map loader
|
||||
config.module.rules.push({ |
||||
test: /\.js$/, |
||||
use: ["source-map-loader"], |
||||
enforce: "pre" |
||||
}) |
||||
|
||||
config.ignoreWarnings = [/Failed to parse source map/] // ignore source-map-loader warnings
|
||||
|
||||
|
||||
// set minimizer
|
||||
config.optimization.minimizer = [ |
||||
new TerserPlugin({ |
||||
parallel: true, |
||||
terserOptions: { |
||||
ecma: 2015, |
||||
compress: false, |
||||
mangle: false, |
||||
format: { |
||||
comments: false, |
||||
}, |
||||
}, |
||||
extractComments: false, |
||||
}), |
||||
new CssMinimizerPlugin(), |
||||
]; |
||||
|
||||
config.watchOptions = { |
||||
ignored: /node_modules/ |
||||
} |
||||
} |
||||
|
||||
return config; |
||||
}); |
||||
|
||||
@ -0,0 +1,34 @@ |
||||
{ |
||||
"extends": [ |
||||
"plugin:@nrwl/nx/react", |
||||
"../../.eslintrc.json" |
||||
], |
||||
"ignorePatterns": [ |
||||
"!**/*" |
||||
], |
||||
"overrides": [ |
||||
{ |
||||
"files": [ |
||||
"*.ts", |
||||
"*.tsx", |
||||
"*.js", |
||||
"*.jsx" |
||||
], |
||||
"rules": {} |
||||
}, |
||||
{ |
||||
"files": [ |
||||
"*.ts", |
||||
"*.tsx" |
||||
], |
||||
"rules": {} |
||||
}, |
||||
{ |
||||
"files": [ |
||||
"*.js", |
||||
"*.jsx" |
||||
], |
||||
"rules": {} |
||||
} |
||||
] |
||||
} |
||||
@ -0,0 +1,13 @@ |
||||
{ |
||||
"semi": false, |
||||
"singleQuote": true, |
||||
"trailingComma": "all", |
||||
"printWidth": 120, |
||||
"tabWidth": 2, |
||||
"useTabs": false, |
||||
"arrowParens": "avoid", |
||||
"bracketSpacing": true, |
||||
"jsxBracketSameLine": false, |
||||
"jsxSingleQuote": false, |
||||
"endOfLine": "lf" |
||||
} |
||||
@ -0,0 +1,61 @@ |
||||
{ |
||||
"name": "doc-gen", |
||||
"$schema": "../../node_modules/nx/schemas/project-schema.json", |
||||
"sourceRoot": "apps/doc-gen/src", |
||||
"projectType": "application", |
||||
"implicitDependencies": [ |
||||
], |
||||
"targets": { |
||||
"build": { |
||||
"executor": "@nrwl/webpack:webpack", |
||||
"outputs": ["{options.outputPath}"], |
||||
"defaultConfiguration": "development", |
||||
"options": { |
||||
"compiler": "babel", |
||||
"outputPath": "dist/apps/doc-gen", |
||||
"index": "apps/doc-gen/src/index.html", |
||||
"baseHref": "./", |
||||
"main": "apps/doc-gen/src/main.tsx", |
||||
"tsConfig": "apps/doc-gen/tsconfig.app.json", |
||||
"assets": [ |
||||
"apps/doc-gen/src/favicon.ico", |
||||
"apps/doc-gen/src/profile.json" |
||||
], |
||||
"styles": [], |
||||
"scripts": [], |
||||
"webpackConfig": "apps/doc-gen/webpack.config.js" |
||||
}, |
||||
"configurations": { |
||||
"development": { |
||||
}, |
||||
"production": { |
||||
"fileReplacements": [ |
||||
{ |
||||
"replace": "apps/doc-gen/src/environments/environment.ts", |
||||
"with": "apps/doc-gen/src/environments/environment.prod.ts" |
||||
} |
||||
] |
||||
} |
||||
} |
||||
}, |
||||
"serve": { |
||||
"executor": "@nrwl/webpack:dev-server", |
||||
"defaultConfiguration": "development", |
||||
"options": { |
||||
"buildTarget": "doc-gen:build", |
||||
"hmr": true, |
||||
"baseHref": "/" |
||||
}, |
||||
"configurations": { |
||||
"development": { |
||||
"buildTarget": "doc-gen:build:development", |
||||
"port": 6003 |
||||
}, |
||||
"production": { |
||||
"buildTarget": "doc-gen:build:production" |
||||
} |
||||
} |
||||
} |
||||
}, |
||||
"tags": [] |
||||
} |
||||
@ -0,0 +1,3 @@ |
||||
body { |
||||
margin: 0; |
||||
} |
||||
@ -0,0 +1,41 @@ |
||||
import React, { useState, useEffect } from 'react' |
||||
|
||||
import './App.css' |
||||
import { DocGenClient } from './docgen-client' |
||||
import { Build } from './docgen/site' |
||||
|
||||
export const client = new DocGenClient() |
||||
|
||||
const App = () => { |
||||
// eslint-disable-next-line @typescript-eslint/no-unused-vars
|
||||
const [themeType, setThemeType] = useState<string>('dark'); |
||||
const [hasBuild, setHasBuild] = useState<boolean>(false); |
||||
const [fileName, setFileName] = useState<string>(''); |
||||
|
||||
useEffect(() => { |
||||
const watchThemeSwitch = async () => { |
||||
client.eventEmitter.on('themeChanged', (theme: string) => { |
||||
setThemeType(theme) |
||||
}) |
||||
client.eventEmitter.on('compilationFinished', (build: Build, fileName: string) => { |
||||
setHasBuild(true) |
||||
setFileName(fileName) |
||||
}) |
||||
client.eventEmitter.on('docsGenerated', (docs: string[]) => { |
||||
}) |
||||
} |
||||
watchThemeSwitch() |
||||
}, []) |
||||
|
||||
return ( |
||||
<div className="p-3"> |
||||
<h5 className="h-5 mb-3">Compile a Solidity contract and generate its documentation as Markdown. (Right-click on a contract in the File Explorer and select "Generate Docs" from the context menu.).</h5> |
||||
{fileName && <div className="border-bottom border-top px-2 py-3 justify-center align-items-center d-flex"> |
||||
<h6>File: {fileName}</h6> |
||||
</div>} |
||||
{hasBuild && <button className="btn btn-primary btn-block mt-4" onClick={() => client.generateDocs()}>Generate Docs</button>} |
||||
</div> |
||||
) |
||||
} |
||||
|
||||
export default App |
||||
@ -0,0 +1,93 @@ |
||||
/* eslint-disable @typescript-eslint/no-explicit-any */ |
||||
import { PluginClient } from '@remixproject/plugin' |
||||
import { CompilationResult, SourceWithTarget, customAction } from '@remixproject/plugin-api' |
||||
import { createClient } from '@remixproject/plugin-webview' |
||||
import EventEmitter from 'events' |
||||
import { Config, defaults } from './docgen/config' |
||||
import { Build, buildSite } from './docgen/site' |
||||
import { loadTemplates } from './docgen/templates' |
||||
import { SolcInput, SolcOutput } from 'solidity-ast/solc' |
||||
import { render } from './docgen/render' |
||||
import { normalizeContractPath } from './docgen/utils/normalizeContractPath' |
||||
|
||||
export class DocGenClient extends PluginClient { |
||||
private currentTheme |
||||
public eventEmitter: EventEmitter |
||||
private build: Build |
||||
public docs: string[] = [] |
||||
private fileName: string = '' |
||||
private contractPath: string = '' |
||||
|
||||
constructor() { |
||||
super() |
||||
this.eventEmitter = new EventEmitter() |
||||
this.methods = ['generateDocs', 'openDocs', 'generateDocsCustomAction'] |
||||
createClient(this) |
||||
this.onload().then(async () => { |
||||
await this.setListeners() |
||||
}) |
||||
} |
||||
|
||||
async setListeners() { |
||||
this.currentTheme = await this.call('theme', 'currentTheme') |
||||
|
||||
this.on('theme', 'themeChanged', (theme: any) => { |
||||
this.currentTheme = theme |
||||
this.eventEmitter.emit('themeChanged', this.currentTheme) |
||||
}); |
||||
this.eventEmitter.emit('themeChanged', this.currentTheme) |
||||
|
||||
this.on('solidity', 'compilationFinished', (fileName: string, source: SourceWithTarget, languageVersion: string, data: CompilationResult) => { |
||||
const input: SolcInput = { |
||||
sources: source.sources |
||||
} |
||||
const output: SolcOutput = { |
||||
sources: data.sources as any |
||||
} |
||||
this.build = { |
||||
input: input, |
||||
output: output |
||||
} |
||||
const segmentedPathList = normalizeContractPath(fileName) |
||||
this.fileName = segmentedPathList[segmentedPathList.length - 1] |
||||
this.contractPath = segmentedPathList[0] |
||||
this.eventEmitter.emit('compilationFinished', this.build, this.fileName) |
||||
}) |
||||
} |
||||
|
||||
async generateDocsCustomAction(action: customAction) { |
||||
await this.call('solidity', 'compile', action.path[0]) |
||||
await this.generateDocs() |
||||
} |
||||
|
||||
async docgen(builds: Build[], userConfig?: Config): Promise<void> { |
||||
const config = { ...defaults, ...userConfig } |
||||
config.sourcesDir = this.contractPath !== config.sourcesDir ? this.contractPath : config.sourcesDir |
||||
const templates = await loadTemplates(config.theme, config.root, config.templates) |
||||
const site = buildSite(builds, config, templates.properties ?? {}) |
||||
const renderedSite = render(site, templates, config.collapseNewlines) |
||||
const docs: string[] = [] |
||||
for (const { id, contents } of renderedSite) { |
||||
const temp = `${this.fileName.split('.')[0]}.${id.split('.')[1]}` |
||||
const newFileName = `docs/${temp}` |
||||
await this.call('fileManager', 'setFile', newFileName , contents) |
||||
docs.push(newFileName) |
||||
} |
||||
this.eventEmitter.emit('docsGenerated', docs) |
||||
this.emit('docgen' as any, 'docsGenerated', docs) |
||||
this.docs = docs |
||||
await this.openDocs(docs) |
||||
} |
||||
|
||||
async openDocs(docs: string[]) { |
||||
await this.call('manager', 'activatePlugin', 'doc-viewer') |
||||
await this.call('tabs' as any, 'focus', 'doc-viewer') |
||||
await this.call('doc-viewer' as any, 'viewDocs', docs) |
||||
} |
||||
|
||||
async generateDocs() { |
||||
this.eventEmitter.on('compilationFinished', async (build: Build, fileName: string) => { |
||||
await this.docgen([build]) |
||||
}) |
||||
} |
||||
} |
||||
@ -0,0 +1,35 @@ |
||||
import { VariableDeclaration } from "solidity-ast"; |
||||
|
||||
export function trim(text: string) { |
||||
if (typeof text === 'string') { |
||||
return text.trim(); |
||||
} |
||||
} |
||||
|
||||
export function joinLines(text?: string) { |
||||
if (typeof text === 'string') { |
||||
return text.replace(/\n+/g, ' '); |
||||
} |
||||
} |
||||
|
||||
/** |
||||
* Format a variable as its type followed by its name, if available. |
||||
*/ |
||||
export function formatVariable(v: VariableDeclaration): string { |
||||
return [v.typeName?.typeDescriptions.typeString].concat(v.name || []).join(' '); |
||||
} |
||||
|
||||
export const eq = (a: unknown, b: unknown) => a === b; |
||||
|
||||
export const slug = (str) => { |
||||
if (str === undefined) { |
||||
throw new Error('Missing argument'); |
||||
} |
||||
return str.replace(/\W/g, '-'); |
||||
} |
||||
|
||||
export const names = params => params.map(p => p.name).join(', '); |
||||
|
||||
export const typedParams = params => { |
||||
return params?.map(p => `${p.type}${p.indexed ? ' indexed' : ''}${p.name ? ' ' + p.name : ''}`).join(', '); |
||||
}; |
||||
@ -0,0 +1,180 @@ |
||||
import { EnumDefinition, ErrorDefinition, EventDefinition, FunctionDefinition, ModifierDefinition, ParameterList, StructDefinition, UserDefinedValueTypeDefinition, VariableDeclaration } from 'solidity-ast'; |
||||
import { findAll, isNodeType } from 'solidity-ast/utils'; |
||||
import { NatSpec, parseNatspec } from '../utils/natspec'; |
||||
import { DocItemContext, DOC_ITEM_CONTEXT } from '../site'; |
||||
import { mapValues } from '../utils/map-values'; |
||||
import { DocItem, docItemTypes } from '../doc-item'; |
||||
import { formatVariable, slug } from './helpers'; |
||||
import { PropertyGetter } from '../templates'; |
||||
import { itemType } from '../utils/item-type'; |
||||
|
||||
type TypeDefinition = StructDefinition | EnumDefinition | UserDefinedValueTypeDefinition; |
||||
|
||||
export function type ({ item }: DocItemContext): string { |
||||
return itemType(item); |
||||
} |
||||
|
||||
export function natspec ({ item }: DocItemContext): NatSpec { |
||||
return parseNatspec(item); |
||||
} |
||||
|
||||
export function name({ item }: DocItemContext, original?: unknown): string { |
||||
if (item.nodeType === 'FunctionDefinition') { |
||||
return item.kind === 'function' ? original as string : item.kind; |
||||
} else { |
||||
return original as string; |
||||
} |
||||
} |
||||
|
||||
export function fullName ({ item, contract }: DocItemContext): string { |
||||
if (contract) { |
||||
return `${contract.name}.${item.name}`; |
||||
} else { |
||||
return `${item.name}`; |
||||
} |
||||
} |
||||
|
||||
export function signature ({ item }: DocItemContext): string | undefined { |
||||
switch (item.nodeType) { |
||||
case 'ContractDefinition': |
||||
return undefined; |
||||
|
||||
case 'FunctionDefinition': { |
||||
const { kind, name } = item; |
||||
const params = item.parameters.parameters; |
||||
const returns = item.returnParameters.parameters; |
||||
const head = (kind === 'function' || kind === 'freeFunction') ? [kind, name].join(' ') : kind; |
||||
const res = [ |
||||
`${head}(${params.map(formatVariable).join(', ')})`, |
||||
item.visibility, |
||||
]; |
||||
if (item.stateMutability !== 'nonpayable') { |
||||
res.push(item.stateMutability); |
||||
} |
||||
if (item.virtual) { |
||||
res.push('virtual'); |
||||
} |
||||
if (returns.length > 0) { |
||||
res.push(`returns (${returns.map(formatVariable).join(', ')})`); |
||||
} |
||||
return res.join(' '); |
||||
} |
||||
|
||||
case 'EventDefinition': { |
||||
const params = item.parameters.parameters; |
||||
return `event ${item.name}(${params.map(formatVariable).join(', ')})`; |
||||
} |
||||
|
||||
case 'ErrorDefinition': { |
||||
const params = item.parameters.parameters; |
||||
return `error ${item.name}(${params.map(formatVariable).join(', ')})`; |
||||
} |
||||
|
||||
case 'ModifierDefinition': { |
||||
const params = item.parameters.parameters; |
||||
return `modifier ${item.name}(${params.map(formatVariable).join(', ')})`; |
||||
} |
||||
|
||||
case 'VariableDeclaration': |
||||
return formatVariable(item); |
||||
} |
||||
} |
||||
|
||||
interface Param extends VariableDeclaration { |
||||
type: string; |
||||
natspec?: string; |
||||
}; |
||||
|
||||
function getParams (params: ParameterList, natspec: NatSpec['params'] | NatSpec['returns']): Param[] { |
||||
return params.parameters.map((p, i) => ({ |
||||
...p, |
||||
type: p.typeDescriptions.typeString!, |
||||
natspec: natspec?.find((q, j) => q.name === undefined ? i === j : p.name === q.name)?.description, |
||||
})); |
||||
} |
||||
|
||||
export function params ({ item }: DocItemContext): Param[] | undefined { |
||||
if ('parameters' in item) { |
||||
return getParams(item.parameters, natspec(item[DOC_ITEM_CONTEXT]).params); |
||||
} |
||||
} |
||||
|
||||
export function returns ({ item }: DocItemContext): Param[] | undefined { |
||||
if ('returnParameters' in item) { |
||||
return getParams(item.returnParameters, natspec(item[DOC_ITEM_CONTEXT]).returns); |
||||
} |
||||
} |
||||
|
||||
export function items ({ item }: DocItemContext): DocItem[] | undefined { |
||||
return (item.nodeType === 'ContractDefinition') |
||||
? item.nodes.filter(isNodeType(docItemTypes)).filter(n => !('visibility' in n) || n.visibility !== 'private') |
||||
: undefined; |
||||
} |
||||
|
||||
export function functions ({ item }: DocItemContext): FunctionDefinition[] | undefined { |
||||
return [...findAll('FunctionDefinition', item)].filter(f => f.visibility !== 'private'); |
||||
} |
||||
|
||||
export function events ({ item }: DocItemContext): EventDefinition[] | undefined { |
||||
return [...findAll('EventDefinition', item)]; |
||||
} |
||||
|
||||
export function modifiers ({ item }: DocItemContext): ModifierDefinition[] | undefined { |
||||
return [...findAll('ModifierDefinition', item)]; |
||||
} |
||||
|
||||
export function errors ({ item }: DocItemContext): ErrorDefinition[] | undefined { |
||||
return [...findAll('ErrorDefinition', item)]; |
||||
} |
||||
|
||||
export function variables ({ item }: DocItemContext): VariableDeclaration[] | undefined { |
||||
return (item.nodeType === 'ContractDefinition') |
||||
? item.nodes.filter(isNodeType('VariableDeclaration')).filter(v => v.stateVariable && v.visibility !== 'private') |
||||
: undefined; |
||||
} |
||||
|
||||
export function types ({ item }: DocItemContext): TypeDefinition[] | undefined { |
||||
return [...findAll(['StructDefinition', 'EnumDefinition', 'UserDefinedValueTypeDefinition'], item)]; |
||||
} |
||||
export function anchor({ item, contract }: DocItemContext) { |
||||
let res = ''; |
||||
if (contract) { |
||||
res += contract.name + '-'; |
||||
} |
||||
res += item.name; |
||||
if ('parameters' in item) { |
||||
const signature = item.parameters.parameters.map(v => v.typeName.typeDescriptions.typeString).join(','); |
||||
res += slug('(' + signature + ')'); |
||||
} |
||||
if (isNodeType('VariableDeclaration', item)) { |
||||
res += '-' + slug(item.typeName.typeDescriptions.typeString); |
||||
} |
||||
return res; |
||||
} |
||||
|
||||
export function inheritance ({ item, build }: DocItemContext) { |
||||
if (!isNodeType('ContractDefinition', item)) { |
||||
throw new Error('used inherited-items on non-contract'); |
||||
} |
||||
|
||||
return item.linearizedBaseContracts |
||||
.map(id => build.deref('ContractDefinition', id)) |
||||
.filter((c, i) => c.name !== 'Context' || i === 0); |
||||
} |
||||
|
||||
export function hasfunctions ({ item }: DocItemContext) { |
||||
return (item as any).inheritance.some(c => c.functions.length > 0); |
||||
} |
||||
|
||||
export function hasevents ({ item }: DocItemContext) { |
||||
return (item as any).inheritance.some(c => c.events.length > 0); |
||||
} |
||||
|
||||
export function inheritedfunctions ({ item }: DocItemContext) { |
||||
const { inheritance } = (item as any) |
||||
const baseFunctions = new Set(inheritance.flatMap(c => c.functions.flatMap(f => f.baseFunctions ?? []))); |
||||
return inheritance.map((contract, i) => ({ |
||||
contract, |
||||
functions: contract.functions.filter(f => !baseFunctions.has(f.id) && (f.name !== 'constructor' || i === 0)), |
||||
})) |
||||
} |
||||
@ -0,0 +1,84 @@ |
||||
import type { SourceUnit } from 'solidity-ast'; |
||||
import type { DocItem } from './doc-item'; |
||||
import type { PageAssigner, PageStructure } from './site'; |
||||
|
||||
export interface UserConfig { |
||||
/** |
||||
* The directory where rendered pages will be written. |
||||
* Defaults to 'docs'. |
||||
*/ |
||||
outputDir?: string; |
||||
|
||||
/** |
||||
* A directory of custom templates that should take precedence over the |
||||
* theme's templates. |
||||
*/ |
||||
templates?: string; |
||||
|
||||
/** |
||||
* The name of the built-in templates that will be used by default. |
||||
* Defaults to 'markdown'. |
||||
*/ |
||||
theme?: string; |
||||
|
||||
/** |
||||
* The way documentable items (contracts, functions, custom errors, etc.) |
||||
* will be organized in pages. Built in options are: |
||||
* - 'single': all items in one page |
||||
* - 'items': one page per item |
||||
* - 'files': one page per input Solidity file |
||||
* More customization is possible by defining a function that returns a page |
||||
* path given the AST node for the item and the source unit where it is |
||||
* defined. |
||||
* Defaults to 'single'. |
||||
*/ |
||||
pages?: 'single' | 'items' | 'files' | PageAssigner; |
||||
|
||||
/** |
||||
* An array of sources subdirectories that should be excluded from |
||||
* documentation, relative to the contract sources directory. |
||||
*/ |
||||
exclude?: string[]; |
||||
|
||||
/** |
||||
* Clean up the output by collapsing 3 or more contiguous newlines into only 2. |
||||
* Enabled by default. |
||||
*/ |
||||
collapseNewlines?: boolean; |
||||
|
||||
/** |
||||
* The extension for generated pages. |
||||
* Defaults to '.md'. |
||||
*/ |
||||
pageExtension?: string; |
||||
} |
||||
|
||||
////////////////////////////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
// Other config parameters that will be provided by the environment (e.g. Hardhat)
|
||||
// rather than by the user manually, unless using the library directly.
|
||||
export interface Config extends UserConfig { |
||||
/** |
||||
* The root directory relative to which 'outputDir', 'sourcesDir', and |
||||
* 'templates' are specified. Defaults to the working directory. |
||||
*/ |
||||
root?: string; |
||||
|
||||
/** |
||||
* The Solidity sources directory. |
||||
*/ |
||||
sourcesDir?: string; |
||||
} |
||||
|
||||
export type FullConfig = Required<Config>; |
||||
|
||||
export const defaults: Omit<FullConfig, 'templates'> = { |
||||
root: process.cwd(), |
||||
sourcesDir: 'contracts', |
||||
outputDir: 'docs', |
||||
pages: 'single', |
||||
exclude: [], |
||||
theme: 'markdown', |
||||
collapseNewlines: true, |
||||
pageExtension: '.md', |
||||
}; |
||||
@ -0,0 +1,27 @@ |
||||
import { ContractDefinition, ImportDirective, PragmaDirective, SourceUnit, UsingForDirective } from "solidity-ast"; |
||||
import { Node, NodeType, NodeTypeMap } from "solidity-ast/node"; |
||||
import { AssertEqual } from "./utils/assert-equal-types"; |
||||
|
||||
export type DocItem = Exclude< |
||||
SourceUnit['nodes'][number] | ContractDefinition['nodes'][number], |
||||
ImportDirective | PragmaDirective | UsingForDirective |
||||
>; |
||||
|
||||
export const docItemTypes = [ |
||||
'ContractDefinition', |
||||
'EnumDefinition', |
||||
'ErrorDefinition', |
||||
'EventDefinition', |
||||
'FunctionDefinition', |
||||
'ModifierDefinition', |
||||
'StructDefinition', |
||||
'UserDefinedValueTypeDefinition', |
||||
'VariableDeclaration', |
||||
] as const; |
||||
|
||||
// Make sure at compile time that docItemTypes contains exactly the node types of DocItem.
|
||||
const _: AssertEqual<typeof docItemTypes[number], DocItem['nodeType']> = true; |
||||
|
||||
export function isDocItem(node: Node): node is DocItem { |
||||
return (docItemTypes as readonly string[]).includes(node.nodeType); |
||||
} |
||||
@ -0,0 +1,87 @@ |
||||
import Handlebars, { RuntimeOptions } from 'handlebars'; |
||||
import { Site, Page, DocItemWithContext, DOC_ITEM_CONTEXT } from './site'; |
||||
import { Templates } from './templates'; |
||||
import { itemType } from './utils/item-type'; |
||||
import fs from 'fs'; |
||||
|
||||
export interface RenderedPage { |
||||
id: string; |
||||
contents: string; |
||||
} |
||||
|
||||
interface TemplateOptions { |
||||
data: { |
||||
site: Site; |
||||
}; |
||||
} |
||||
|
||||
export function render(site: Site, templates: Templates, collapseNewlines?: boolean): RenderedPage[] { |
||||
const renderPage = buildRenderer(templates); |
||||
const renderedPages: RenderedPage[] = []; |
||||
for (const page of site.pages) { |
||||
let contents = renderPage(page, { data: { site } }); |
||||
if (collapseNewlines) { |
||||
contents = contents.replace(/\n{3,}/g, '\n\n'); |
||||
} |
||||
renderedPages.push({ |
||||
id: page.id, |
||||
contents, |
||||
}); |
||||
} |
||||
return renderedPages; |
||||
} |
||||
|
||||
export const itemPartialName = (item: DocItemWithContext) => itemType(item).replace(/ /g, '-').toLowerCase(); |
||||
|
||||
function itemPartial(item: DocItemWithContext, options?: RuntimeOptions) { |
||||
if (!item.__item_context) { |
||||
throw new Error(`Partial 'item' used in unsupported context (not a doc item)`); |
||||
} |
||||
const partial = options?.partials?.[itemPartialName(item)]; |
||||
if (!partial) { |
||||
throw new Error(`Missing partial '${itemPartialName(item)}'`); |
||||
} |
||||
return partial(item, options); |
||||
} |
||||
|
||||
function readmeHelper(H: typeof Handlebars, path: string, opts: RuntimeOptions) { |
||||
const items: DocItemWithContext[] = opts.data.root.items; |
||||
const renderedItems = Object.fromEntries( |
||||
items.map(item => [ |
||||
item.name, |
||||
new H.SafeString( |
||||
H.compile('{{>item}}')(item, opts), |
||||
), |
||||
]), |
||||
); |
||||
return new H.SafeString( |
||||
H.compile(fs.readFileSync(path, 'utf8'))(renderedItems, opts), |
||||
); |
||||
} |
||||
|
||||
function buildRenderer(templates: Templates): (page: Page, options: TemplateOptions) => string { |
||||
const pageTemplate = templates.partials?.page; |
||||
if (pageTemplate === undefined) { |
||||
throw new Error(`Missing 'page' template`); |
||||
} |
||||
|
||||
const H = Handlebars.create(); |
||||
|
||||
for (const [name, getBody] of Object.entries(templates.partials ?? {})) { |
||||
let partial: HandlebarsTemplateDelegate | undefined; |
||||
H.registerPartial(name, (...args) => { |
||||
partial ??= H.compile(getBody()); |
||||
return partial(...args); |
||||
}); |
||||
} |
||||
|
||||
H.registerHelper('readme', (path: string, opts: RuntimeOptions) => readmeHelper(H, path, opts)); |
||||
|
||||
for (const [name, fn] of Object.entries(templates.helpers ?? {})) { |
||||
H.registerHelper(name, fn); |
||||
} |
||||
|
||||
H.registerPartial('item', itemPartial); |
||||
|
||||
return H.compile('{{>page}}'); |
||||
} |
||||
@ -0,0 +1,138 @@ |
||||
import path from 'path'; |
||||
import { ContractDefinition, SourceUnit } from 'solidity-ast'; |
||||
import { SolcOutput, SolcInput } from 'solidity-ast/solc'; |
||||
import { astDereferencer, ASTDereferencer, findAll, isNodeType, srcDecoder, SrcDecoder } from 'solidity-ast/utils'; |
||||
import { FullConfig } from './config'; |
||||
import { DocItem, docItemTypes, isDocItem } from './doc-item'; |
||||
import { Properties } from './templates'; |
||||
import { clone } from './utils/clone'; |
||||
import { isChild } from './utils/is-child'; |
||||
import { mapValues } from './utils/map-values'; |
||||
import { defineGetterMemoized } from './utils/memoized-getter'; |
||||
|
||||
export interface Build { |
||||
input: SolcInput; |
||||
output: SolcOutput; |
||||
} |
||||
|
||||
export interface BuildContext extends Build { |
||||
deref: ASTDereferencer; |
||||
decodeSrc: SrcDecoder; |
||||
} |
||||
|
||||
export type SiteConfig = Pick<FullConfig, 'pages' | 'exclude' | 'sourcesDir' | 'pageExtension'>; |
||||
export type PageStructure = SiteConfig['pages']; |
||||
export type PageAssigner = ((item: DocItem, file: SourceUnit, config: SiteConfig) => string | undefined); |
||||
|
||||
export const pageAssigner: Record<PageStructure & string, PageAssigner> = { |
||||
single: (_1, _2, { pageExtension: ext }) => 'index' + ext, |
||||
items: (item, _, { pageExtension: ext }) => item.name + ext, |
||||
files: (_, file, { pageExtension: ext, sourcesDir }) => |
||||
path.relative(sourcesDir, file.absolutePath).replace('.sol', ext), |
||||
}; |
||||
|
||||
export interface Site { |
||||
items: DocItemWithContext[]; |
||||
pages: Page[]; |
||||
} |
||||
|
||||
export interface Page { |
||||
id: string; |
||||
items: DocItemWithContext[]; |
||||
} |
||||
|
||||
export const DOC_ITEM_CONTEXT = '__item_context' as const; |
||||
export type DocItemWithContext = DocItem & { [DOC_ITEM_CONTEXT]: DocItemContext }; |
||||
|
||||
export interface DocItemContext { |
||||
page?: string; |
||||
item: DocItemWithContext; |
||||
contract?: ContractDefinition; |
||||
file: SourceUnit; |
||||
build: BuildContext; |
||||
} |
||||
|
||||
export function buildSite (builds: Build[], siteConfig: SiteConfig, properties: Properties = {}): Site { |
||||
const assign = typeof siteConfig.pages === 'string' ? pageAssigner[siteConfig.pages] : siteConfig.pages; |
||||
|
||||
const seen = new Set<string>(); |
||||
const items: DocItemWithContext[] = []; |
||||
const pages: Record<string, DocItemWithContext[]> = {}; |
||||
|
||||
// eslint-disable-next-line prefer-const
|
||||
for (let { input, output } of builds) { |
||||
// Clone because we will mutate in order to add item context.
|
||||
output = { ...output, sources: clone(output.sources) }; |
||||
|
||||
const deref = astDereferencer(output); |
||||
const decodeSrc = srcDecoder(input, output); |
||||
const build = { input, output, deref, decodeSrc }; |
||||
|
||||
for (const { ast: file } of Object.values(output.sources)) { |
||||
const isNewFile = !seen.has(file.absolutePath); |
||||
seen.add(file.absolutePath); |
||||
|
||||
for (const topLevelItem of file.nodes) { |
||||
if (!isDocItem(topLevelItem)) continue; |
||||
|
||||
const page = assignIfIncludedSource(assign, topLevelItem, file, siteConfig); |
||||
|
||||
const withContext = defineContext(topLevelItem, build, file, page); |
||||
defineProperties(withContext, properties); |
||||
|
||||
if (isNewFile && page !== undefined) { |
||||
(pages[page] ??= []).push(withContext); |
||||
items.push(withContext); |
||||
} |
||||
|
||||
if (!isNodeType('ContractDefinition', topLevelItem)) { |
||||
continue; |
||||
} |
||||
|
||||
for (const item of topLevelItem.nodes) { |
||||
if (!isDocItem(item)) continue; |
||||
if (isNewFile && page !== undefined) items.push(item as DocItemWithContext); |
||||
const contract = topLevelItem.nodeType === 'ContractDefinition' ? topLevelItem : undefined; |
||||
const withContext = defineContext(item, build, file, page, contract); |
||||
defineProperties(withContext, properties); |
||||
} |
||||
} |
||||
} |
||||
} |
||||
|
||||
return { |
||||
items, |
||||
pages: Object.entries(pages).map(([id, pageItems]) => ({ id, items: pageItems })), |
||||
}; |
||||
} |
||||
|
||||
function defineContext (item: DocItem, build: BuildContext, file: SourceUnit, page?: string, contract?: ContractDefinition): DocItemWithContext { |
||||
return Object.assign(item, { |
||||
[DOC_ITEM_CONTEXT]: { build, file, contract, page, item: item as DocItemWithContext }, |
||||
}); |
||||
} |
||||
|
||||
function defineProperties (item: DocItemWithContext, properties: Properties) { |
||||
for (const [prop, fn] of Object.entries(properties)) { |
||||
const original: unknown = (item as any)[prop]; |
||||
defineGetterMemoized(item as any, prop, () => fn(item.__item_context, original)); |
||||
} |
||||
} |
||||
|
||||
function assignIfIncludedSource ( |
||||
assign: PageAssigner, |
||||
item: DocItem, |
||||
file: SourceUnit, |
||||
config: SiteConfig, |
||||
) { |
||||
return isFileIncluded(file.absolutePath, config) |
||||
? assign(item, file, config) |
||||
: undefined; |
||||
} |
||||
|
||||
function isFileIncluded (file: string, config: SiteConfig) { |
||||
return ( |
||||
isChild(file, config.sourcesDir) && |
||||
config.exclude.every(e => !isChild(file, path.join(config.sourcesDir, e))) |
||||
); |
||||
} |
||||
@ -0,0 +1,110 @@ |
||||
/* eslint-disable @typescript-eslint/no-var-requires */ |
||||
import { mapKeys } from './utils/map-keys'; |
||||
import { DocItemContext } from './site'; |
||||
|
||||
import * as defaultProperties from './common/properties'; |
||||
import * as themeHelpers from './themes/markdown/helpers' |
||||
|
||||
const common = require('./themes/markdown/common.hbs'); |
||||
const contract = require('./themes/markdown/contract.hbs'); |
||||
const enum_ = require('./themes/markdown/enum.hbs'); |
||||
const error = require('./themes/markdown/error.hbs'); |
||||
const event = require('./themes/markdown/event.hbs'); |
||||
const function_ = require('./themes/markdown/function.hbs'); |
||||
const modifier = require('./themes/markdown/modifier.hbs'); |
||||
const page = require('./themes/markdown/page.hbs'); |
||||
const struct = require('./themes/markdown/struct.hbs'); |
||||
const variable = require('./themes/markdown/variable.hbs'); |
||||
const userDefinedValueType = require('./themes/markdown/user-defined-value-type.hbs'); |
||||
|
||||
export type PropertyGetter = (ctx: DocItemContext, original?: unknown) => unknown; |
||||
export type Properties = Record<string, PropertyGetter>; |
||||
|
||||
export interface Templates { |
||||
partials?: Record<string, () => string>; |
||||
helpers?: Record<string, (...args: unknown[]) => string>; |
||||
properties?: Record<string, PropertyGetter>; |
||||
} |
||||
|
||||
/** |
||||
* Loads the templates that will be used for rendering a site based on a |
||||
* default theme and user templates. |
||||
* |
||||
* The result contains all partials, helpers, and property getters defined in |
||||
* the user templates and the default theme, where the user's take precedence |
||||
* if there is a clash. Additionally, all theme partials and helpers are |
||||
* included with the theme prefix, e.g. `markdown/contract` will be a partial. |
||||
*/ |
||||
export async function loadTemplates(defaultTheme: string, root: string, userTemplatesPath?: string): Promise<Templates> { |
||||
const themes = await readThemes(); |
||||
|
||||
// Initialize templates with the default theme.
|
||||
const templates: Required<Templates> = { |
||||
partials: { ...themes[defaultTheme]?.partials }, |
||||
helpers: { ...themes[defaultTheme]?.helpers }, |
||||
properties: { ...defaultProperties }, |
||||
}; |
||||
|
||||
|
||||
// Add partials and helpers from all themes, prefixed with the theme name.
|
||||
for (const [themeName, theme] of Object.entries(themes)) { |
||||
const addPrefix = (k: string) => `${themeName}/${k}`; |
||||
Object.assign(templates.partials, mapKeys(theme.partials, addPrefix)); |
||||
Object.assign(templates.helpers, mapKeys(theme.helpers, addPrefix)); |
||||
} |
||||
|
||||
return templates; |
||||
} |
||||
|
||||
/** |
||||
* Read templates and helpers from a directory. |
||||
*/ |
||||
export async function readTemplates(): Promise<Required<Templates>> { |
||||
return { |
||||
partials: await readPartials(), |
||||
helpers: await readHelpers('helpers'), |
||||
properties: await readHelpers('properties'), |
||||
}; |
||||
} |
||||
|
||||
async function readPartials() { |
||||
const partials: NonNullable<Templates['partials']> = {}; |
||||
|
||||
partials["common"] = () => common |
||||
partials["contract"] = () => contract |
||||
partials["enum"] = () => enum_ |
||||
partials["error"] = () => error |
||||
partials["event"] = () => event |
||||
partials["function"] = () => function_ |
||||
partials["modifier"] = () => modifier |
||||
partials["page"] = () => page |
||||
partials["struct"] = () => struct |
||||
partials["variable"] = () => variable |
||||
partials["user-defined-value-type"] = () => userDefinedValueType |
||||
|
||||
return partials; |
||||
} |
||||
|
||||
async function readHelpers(name: string) { |
||||
|
||||
const helpers: Record<string, (...args: any[]) => any> = {}; |
||||
|
||||
for (const name in themeHelpers) { |
||||
if (typeof themeHelpers[name] === 'function') { |
||||
helpers[name] = themeHelpers[name]; |
||||
} |
||||
} |
||||
|
||||
return helpers; |
||||
} |
||||
|
||||
/** |
||||
* Reads all built-in themes into an object. Partials will always be found in |
||||
* src/themes, whereas helpers may instead be found in dist/themes if TypeScript |
||||
* can't be imported directly. |
||||
*/ |
||||
async function readThemes(): Promise<Record<string, Required<Templates>>> { |
||||
const themes: Record<string, Required<Templates>> = {} |
||||
themes['markdown'] = await readTemplates() |
||||
return themes |
||||
} |
||||
@ -0,0 +1,34 @@ |
||||
{{h}} {{name}} |
||||
|
||||
{{#if signature}} |
||||
```solidity |
||||
{{{signature}}} |
||||
``` |
||||
{{/if}} |
||||
|
||||
{{{natspec.notice}}} |
||||
|
||||
{{#if natspec.dev}} |
||||
_{{{natspec.dev}}}_ |
||||
{{/if}} |
||||
|
||||
{{#if natspec.params}} |
||||
{{h 2}} Parameters |
||||
|
||||
| Name | Type | Description | |
||||
| ---- | ---- | ----------- | |
||||
{{#each params}} |
||||
| {{name}} | {{type}} | {{{joinLines natspec}}} | |
||||
{{/each}} |
||||
{{/if}} |
||||
|
||||
{{#if natspec.returns}} |
||||
{{h 2}} Return Values |
||||
|
||||
| Name | Type | Description | |
||||
| ---- | ---- | ----------- | |
||||
{{#each returns}} |
||||
| {{#if name}}{{name}}{{else}}[{{@index}}]{{/if}} | {{type}} | {{{joinLines natspec}}} | |
||||
{{/each}} |
||||
{{/if}} |
||||
|
||||
@ -0,0 +1,46 @@ |
||||
{{>common}} |
||||
|
||||
{{h 2}} Contract |
||||
{{name}} : {{__item_context.file.absolutePath}} |
||||
|
||||
{{{natspec.dev}}} |
||||
|
||||
{{#if modifiers}} |
||||
{{s}} |
||||
{{h 2}} Modifiers: |
||||
{{#each modifiers}} |
||||
{{#hsection}} |
||||
{{>item}} |
||||
{{/hsection}} |
||||
{{/each}} |
||||
{{/if}} |
||||
|
||||
{{#if hasfunctions}} |
||||
{{s}} |
||||
{{h 2}} Functions: |
||||
{{#each inheritedfunctions}} |
||||
{{#unless @first}} |
||||
inherits {{contract.name}}: |
||||
{{/unless}} |
||||
{{#each functions}} |
||||
{{#hsection}} |
||||
{{>item}} |
||||
{{/hsection}} |
||||
{{/each}} |
||||
{{/each}} |
||||
{{/if}} |
||||
|
||||
{{#if hasevents}} |
||||
{{s}} |
||||
{{h 2}} Events: |
||||
{{#each inheritance}} |
||||
{{#unless @first}} |
||||
inherits {{name}}: |
||||
{{/unless}} |
||||
{{#each events}} |
||||
{{#hsection}} |
||||
{{>item}} |
||||
{{/hsection}} |
||||
{{/each}} |
||||
{{/each}} |
||||
{{/if}} |
||||
@ -0,0 +1,9 @@ |
||||
{{>common}} |
||||
|
||||
```solidity |
||||
enum {{name}} { |
||||
{{#each members}} |
||||
{{name}}{{#unless @last}},{{/unless}} |
||||
{{/each}} |
||||
} |
||||
``` |
||||
@ -0,0 +1 @@ |
||||
{{>common}} |
||||
@ -0,0 +1 @@ |
||||
{{>common}} |
||||
@ -0,0 +1 @@ |
||||
{{>common}} |
||||
@ -0,0 +1,62 @@ |
||||
import { HelperOptions, Utils } from 'handlebars'; |
||||
|
||||
export * from '../../common/helpers'; |
||||
|
||||
/** |
||||
* Returns a Markdown heading marker. An optional number increases the heading level. |
||||
* |
||||
* Input Output |
||||
* {{h}} {{name}} # Name |
||||
* {{h 2}} {{name}} ## Name |
||||
*/ |
||||
export function h(opts: HelperOptions): string; |
||||
export function h(hsublevel: number, opts: HelperOptions): string; |
||||
export function h(hsublevel: number | HelperOptions, opts?: HelperOptions) { |
||||
const { hlevel } = getHLevel(hsublevel, opts); |
||||
return new Array(hlevel).fill('#').join(''); |
||||
}; |
||||
|
||||
/** |
||||
* Delineates a section where headings should be increased by 1 or a custom number. |
||||
* |
||||
* {{#hsection}} |
||||
* {{>partial-with-headings}} |
||||
* {{/hsection}} |
||||
*/ |
||||
export function hsection(opts: HelperOptions): string; |
||||
export function hsection(hsublevel: number, opts: HelperOptions): string; |
||||
export function hsection(this: unknown, hsublevel: number | HelperOptions, opts?: HelperOptions) { |
||||
let hlevel; |
||||
({ hlevel, opts } = getHLevel(hsublevel, opts)); |
||||
opts.data = Utils.createFrame(opts.data); |
||||
opts.data.hlevel = hlevel; |
||||
return opts.fn(this as unknown, opts); |
||||
} |
||||
|
||||
/** |
||||
* Returns a Markdown heading marker. An optional number increases the heading level. |
||||
* |
||||
* Input Output |
||||
* {{h}} {{name}} # Name |
||||
* {{h 2}} {{name}} ## Name |
||||
*/ |
||||
export function s(opts: HelperOptions): string; |
||||
export function s(hsublevel: number, opts: HelperOptions): string; |
||||
export function s(hsublevel: number | HelperOptions, opts?: HelperOptions) { |
||||
return ' --- ' |
||||
}; |
||||
|
||||
/** |
||||
* Helper for dealing with the optional hsublevel argument. |
||||
*/ |
||||
function getHLevel(hsublevel: number | HelperOptions, opts?: HelperOptions) { |
||||
if (typeof hsublevel === 'number') { |
||||
opts = opts!; |
||||
hsublevel = Math.max(1, hsublevel); |
||||
} else { |
||||
opts = hsublevel; |
||||
hsublevel = 1; |
||||
} |
||||
const contextHLevel: number = opts.data?.hlevel ?? 0; |
||||
return { opts, hlevel: contextHLevel + hsublevel }; |
||||
} |
||||
@ -0,0 +1 @@ |
||||
{{>common}} |
||||
@ -0,0 +1,8 @@ |
||||
# Solidity API |
||||
|
||||
{{#each items}} |
||||
{{#hsection}} |
||||
{{>item}} |
||||
{{/hsection}} |
||||
|
||||
{{/each}} |
||||
@ -0,0 +1,9 @@ |
||||
{{>common}} |
||||
|
||||
```solidity |
||||
struct {{name}} { |
||||
{{#each members}} |
||||
{{{typeName.typeDescriptions.typeString}}} {{name}}; |
||||
{{/each}} |
||||
} |
||||
``` |
||||
@ -0,0 +1 @@ |
||||
{{>common}} |
||||
@ -0,0 +1 @@ |
||||
{{>common}} |
||||
@ -0,0 +1,13 @@ |
||||
import { DocItemWithContext, DOC_ITEM_CONTEXT } from '../site'; |
||||
|
||||
export class ItemError extends Error { |
||||
constructor(msg: string, item: DocItemWithContext) { |
||||
const ctx = item[DOC_ITEM_CONTEXT]; |
||||
const src = ctx && ctx.build.decodeSrc(item); |
||||
if (src) { |
||||
super(msg + ` (${src})`); |
||||
} else { |
||||
super(msg); |
||||
} |
||||
} |
||||
} |
||||
@ -0,0 +1,5 @@ |
||||
export function arraysEqual<T>(a: T[], b: T[]): boolean; |
||||
export function arraysEqual<T, U>(a: T[], b: T[], mapFn: (x: T) => U): boolean; |
||||
export function arraysEqual<T>(a: T[], b: T[], mapFn = (x: T) => x): boolean { |
||||
return a.length === b.length && a.every((x, i) => mapFn(x) === mapFn(b[i]!)); |
||||
} |
||||
@ -0,0 +1 @@ |
||||
export type AssertEqual<T, U> = [T, U] extends [U, T] ? true : never; |
||||
@ -0,0 +1,6 @@ |
||||
/** |
||||
* Deep cloning good enough for simple objects like solc output. Types are not |
||||
* sound because the function may lose information: non-enumerable properties, |
||||
* symbols, undefined values, prototypes, etc. |
||||
*/ |
||||
export const clone = <T>(obj: T): T => JSON.parse(JSON.stringify(obj)); |
||||
@ -0,0 +1,12 @@ |
||||
// The function below would not be correctly typed if the return type was T[]
|
||||
// because T may itself be an array type and Array.isArray would not know the
|
||||
// difference. Adding IfArray<T> makes sure the return type is always correct.
|
||||
type IfArray<T> = T extends any[] ? T : never; |
||||
|
||||
export function ensureArray<T>(x: T | T[]): T[] | IfArray<T> { |
||||
if (Array.isArray(x)) { |
||||
return x; |
||||
} else { |
||||
return [x]; |
||||
} |
||||
} |
||||
@ -0,0 +1,18 @@ |
||||
/** |
||||
* Iterates over all contiguous matches of the regular expression over the |
||||
* text. Stops as soon as the regular expression no longer matches at the |
||||
* current position. |
||||
*/ |
||||
export function* execAll(re: RegExp, text: string) { |
||||
re = new RegExp(re, re.flags + (re.sticky ? '' : 'y')); |
||||
|
||||
while (true) { |
||||
const match = re.exec(text); |
||||
|
||||
// We break out of the loop if there is no match or if the empty string is
|
||||
// matched because no progress will be made and it will loop indefinitely.
|
||||
if (!match?.[0]) break; |
||||
|
||||
yield match; |
||||
} |
||||
} |
||||
@ -0,0 +1,5 @@ |
||||
import path from 'path'; |
||||
|
||||
export function isChild(file: string, parent: string) { |
||||
return path.normalize(file + path.sep).startsWith(path.normalize(parent + path.sep)); |
||||
} |
||||
@ -0,0 +1,7 @@ |
||||
import { DocItem } from '../doc-item'; |
||||
|
||||
export function itemType(item: DocItem): string { |
||||
return item.nodeType |
||||
.replace(/(Definition|Declaration)$/, '') |
||||
.replace(/(\w)([A-Z])/g, '$1 $2'); |
||||
} |
||||
@ -0,0 +1,4 @@ |
||||
export function mapKeys<T>(obj: Record<string, T>, fn: (key: string) => string): Record<string, T> { |
||||
return Object.fromEntries(Object.entries(obj).map(([k, v]) => [fn(k), v])); |
||||
} |
||||
|
||||
@ -0,0 +1,19 @@ |
||||
export function mapValues<T, U>(obj: Record<string, T>, fn: (value: T) => U): Record<string, U> { |
||||
const res: Record<string, U> = {}; |
||||
for (const [k, v] of Object.entries(obj)) { |
||||
res[k] = fn(v); |
||||
} |
||||
return res; |
||||
} |
||||
|
||||
export function filterValues<T, U extends T>(obj: Record<string, T>, fn: (value: T) => value is U): Record<string, U>; |
||||
export function filterValues<T>(obj: Record<string, T>, fn: (value: T) => boolean): Record<string, T>; |
||||
export function filterValues<T>(obj: Record<string, T>, fn: (value: T) => boolean): Record<string, T> { |
||||
const res: Record<string, T> = {}; |
||||
for (const [k, v] of Object.entries(obj)) { |
||||
if (fn(v)) { |
||||
res[k] = v; |
||||
} |
||||
} |
||||
return res; |
||||
} |
||||
@ -0,0 +1,23 @@ |
||||
export function defineGetterMemoized<K extends keyof any, T, O extends { [k in K]?: T }>(obj: O, key: K, getter: () => T) { |
||||
let state: 'todo' | 'doing' | 'done' = 'todo'; |
||||
let value: T; |
||||
|
||||
Object.defineProperty(obj, key, { |
||||
enumerable: true, |
||||
get() { |
||||
switch (state) { |
||||
case 'done':
|
||||
return value; |
||||
|
||||
case 'doing': |
||||
throw new Error("Detected recursion"); |
||||
|
||||
case 'todo': |
||||
state = 'doing'; |
||||
value = getter(); |
||||
state = 'done'; |
||||
return value; |
||||
} |
||||
} |
||||
}); |
||||
} |
||||
@ -0,0 +1,145 @@ |
||||
import { FunctionDefinition } from 'solidity-ast'; |
||||
import { findAll } from 'solidity-ast/utils'; |
||||
import { DocItemWithContext, DOC_ITEM_CONTEXT } from '../site'; |
||||
import { arraysEqual } from './arrays-equal'; |
||||
import { execAll } from './execall'; |
||||
import { itemType } from './item-type'; |
||||
import { ItemError } from './ItemError'; |
||||
import { readItemDocs } from './read-item-docs'; |
||||
import { getContractsInScope } from './scope'; |
||||
|
||||
export interface NatSpec { |
||||
title?: string; |
||||
notice?: string; |
||||
dev?: string; |
||||
params?: { |
||||
name: string; |
||||
description: string; |
||||
}[]; |
||||
returns?: { |
||||
name?: string; |
||||
description: string; |
||||
}[]; |
||||
custom?: { |
||||
[tag: string]: string; |
||||
}; |
||||
} |
||||
|
||||
export function parseNatspec(item: DocItemWithContext): NatSpec { |
||||
if (!item[DOC_ITEM_CONTEXT]) throw new Error(`Not an item or item is missing context`); |
||||
|
||||
let res: NatSpec = {}; |
||||
|
||||
const docSource = readItemDocs(item); |
||||
const docString = docSource !== undefined |
||||
? cleanUpDocstringFromSource(docSource) |
||||
: 'documentation' in item && item.documentation |
||||
? typeof item.documentation === 'string' |
||||
? item.documentation |
||||
: cleanUpDocstringFromSolc(item.documentation.text) |
||||
: ''; |
||||
|
||||
const tagMatches = execAll( |
||||
/^(?:@(\w+|custom:[a-z][a-z-]*) )?((?:(?!^@(?:\w+|custom:[a-z][a-z-]*) )[^])*)/m, |
||||
docString, |
||||
); |
||||
|
||||
let inheritFrom: FunctionDefinition | undefined; |
||||
|
||||
for (const [, tag = 'notice', content] of tagMatches) { |
||||
if (content === undefined) throw new ItemError('Unexpected error', item); |
||||
|
||||
if (tag === 'dev' || tag === 'notice') { |
||||
res[tag] ??= ''; |
||||
res[tag] += content; |
||||
} |
||||
|
||||
if (tag === 'title') { |
||||
res.title = content.trim(); |
||||
} |
||||
|
||||
if (tag === 'param') { |
||||
const paramMatches = content.match(/(\w+) ([^]*)/); |
||||
if (paramMatches) { |
||||
const [, name, description] = paramMatches as [string, string, string]; |
||||
res.params ??= []; |
||||
res.params.push({ name, description: description.trim() }); |
||||
} |
||||
} |
||||
|
||||
if (tag === 'return') { |
||||
if (!('returnParameters' in item)) { |
||||
throw new ItemError(`Item does not contain return parameters`, item); |
||||
} |
||||
res.returns ??= []; |
||||
const i = res.returns.length; |
||||
const p = item.returnParameters.parameters[i]; |
||||
if (p === undefined) { |
||||
throw new ItemError('Got more @return tags than expected', item); |
||||
} |
||||
if (!p.name) { |
||||
res.returns.push({ description: content.trim() }); |
||||
} else { |
||||
const paramMatches = content.match(/(\w+)( ([^]*))?/); |
||||
if (!paramMatches || paramMatches[1] !== p.name) { |
||||
throw new ItemError(`Expected @return tag to start with name '${p.name}'`, item); |
||||
} |
||||
const [, name, description] = paramMatches as [string, string, string?]; |
||||
res.returns.push({ name, description: description?.trim() ?? '' }); |
||||
} |
||||
} |
||||
|
||||
if (tag?.startsWith('custom:')) { |
||||
const key = tag.replace(/^custom:/, ''); |
||||
res.custom ??= {}; |
||||
res.custom[key] ??= ''; |
||||
res.custom[key] += content; |
||||
} |
||||
|
||||
if (tag === 'inheritdoc') { |
||||
if (!(item.nodeType === 'FunctionDefinition' || item.nodeType === 'VariableDeclaration')) { |
||||
throw new ItemError(`Expected function or variable but saw ${itemType(item)}`, item); |
||||
} |
||||
const parentContractName = content.trim(); |
||||
const parentContract = getContractsInScope(item)[parentContractName]; |
||||
if (!parentContract) { |
||||
throw new ItemError(`Parent contract '${parentContractName}' not found`, item); |
||||
} |
||||
inheritFrom = [...findAll('FunctionDefinition', parentContract)].find(f => item.baseFunctions?.includes(f.id)); |
||||
} |
||||
} |
||||
|
||||
if (docString.length === 0) { |
||||
if ('baseFunctions' in item && item.baseFunctions?.length === 1) { |
||||
const baseFn = item[DOC_ITEM_CONTEXT].build.deref('FunctionDefinition', item.baseFunctions[0]!); |
||||
const shouldInherit = item.nodeType === 'VariableDeclaration' || arraysEqual(item.parameters.parameters, baseFn.parameters.parameters, p => p.name); |
||||
if (shouldInherit) { |
||||
inheritFrom = baseFn; |
||||
} |
||||
} |
||||
} |
||||
|
||||
if (res.dev) res.dev = res.dev.trim(); |
||||
if (res.notice) res.notice = res.notice.trim(); |
||||
|
||||
if (inheritFrom) { |
||||
res = { ...parseNatspec(inheritFrom as DocItemWithContext), ...res }; |
||||
} |
||||
|
||||
return res; |
||||
} |
||||
|
||||
// Fix solc buggy parsing of doc comments.
|
||||
// Reverse engineered from solc behavior.
|
||||
function cleanUpDocstringFromSolc(text: string) { |
||||
return text |
||||
.replace(/\n\n?^[ \t]*(?:\*|\/\/\/)/mg, '\n\n') |
||||
.replace(/^[ \t]?/mg, ''); |
||||
} |
||||
|
||||
function cleanUpDocstringFromSource(text: string) { |
||||
return text |
||||
.replace(/^\/\*\*(.*)\*\/$/s, '$1') |
||||
.trim() |
||||
.replace(/^[ \t]*(\*|\/\/\/)[ \t]?/mg, ''); |
||||
} |
||||
@ -0,0 +1,13 @@ |
||||
|
||||
export function normalizeContractPath(contractPath: string): string[]{ |
||||
const paths = contractPath.split('/') |
||||
const filename = paths[paths.length - 1] |
||||
let folders = '' |
||||
for (let i = 0; i < paths.length - 1; i++) { |
||||
if(i !== paths.length -1) { |
||||
folders += `${paths[i]}/` |
||||
} |
||||
} |
||||
const resultingPath = `${folders}${filename}` |
||||
return [folders,resultingPath, filename] |
||||
} |
||||
@ -0,0 +1,26 @@ |
||||
import { DocItemWithContext, DOC_ITEM_CONTEXT, Build } from '../site'; |
||||
|
||||
export function readItemDocs(item: DocItemWithContext): string | undefined { |
||||
const { build } = item[DOC_ITEM_CONTEXT]; |
||||
// Note that Solidity 0.5 has item.documentation: string even though the
|
||||
// types do not reflect that. This is why we check typeof === object.
|
||||
if ('documentation' in item && item.documentation && typeof item.documentation === 'object') { |
||||
const { source, start, length } = decodeSrc(item.documentation.src, build); |
||||
const content = build.input.sources[source]?.content; |
||||
if (content !== undefined) { |
||||
return Buffer.from(content, 'utf8').slice(start, start + length).toString('utf8'); |
||||
} |
||||
} |
||||
} |
||||
|
||||
function decodeSrc(src: string, build: Build): { source: string; start: number; length: number } { |
||||
const [start, length, sourceId] = src.split(':').map(s => parseInt(s)); |
||||
if (start === undefined || length === undefined || sourceId === undefined) { |
||||
throw new Error(`Bad source string ${src}`); |
||||
} |
||||
const source = Object.keys(build.output.sources).find(s => build.output.sources[s]?.id === sourceId); |
||||
if (source === undefined) { |
||||
throw new Error(`No source with id ${sourceId}`); |
||||
} |
||||
return { source, start, length }; |
||||
} |
||||
@ -0,0 +1,63 @@ |
||||
import { ContractDefinition, SourceUnit } from "solidity-ast"; |
||||
import { findAll, isNodeType } from "solidity-ast/utils"; |
||||
import { DocItemWithContext } from "../site"; |
||||
import { filterValues, mapValues } from './map-values'; |
||||
import { mapKeys } from './map-keys'; |
||||
|
||||
type Definition = SourceUnit['nodes'][number] & { name: string }; |
||||
type Scope = { [name in string]: () => { namespace: Scope } | { definition: Definition } }; |
||||
|
||||
export function getContractsInScope(item: DocItemWithContext) { |
||||
const cache = new WeakMap<SourceUnit, Scope>(); |
||||
|
||||
return filterValues( |
||||
flattenScope(run(item.__item_context.file)), |
||||
isNodeType('ContractDefinition'), |
||||
); |
||||
|
||||
function run(file: SourceUnit): Scope { |
||||
if (cache.has(file)) { |
||||
return cache.get(file)!; |
||||
} |
||||
|
||||
const scope: Scope = {}; |
||||
|
||||
cache.set(file, scope); |
||||
|
||||
for (const c of file.nodes) { |
||||
if ('name' in c) { |
||||
scope[c.name] = () => ({ definition: c }); |
||||
} |
||||
} |
||||
|
||||
for (const i of findAll('ImportDirective', file)) { |
||||
const importedFile = item.__item_context.build.deref('SourceUnit', i.sourceUnit); |
||||
const importedScope = run(importedFile); |
||||
if (i.unitAlias) { |
||||
scope[i.unitAlias] = () => ({ namespace: importedScope }); |
||||
} else if (i.symbolAliases.length === 0) { |
||||
Object.assign(scope, importedScope); |
||||
} else { |
||||
for (const a of i.symbolAliases) { |
||||
// Delayed function call supports circular dependencies
|
||||
scope[a.local ?? a.foreign.name] = importedScope[a.foreign.name] ?? (() => importedScope[a.foreign.name]!()); |
||||
} |
||||
} |
||||
}; |
||||
|
||||
return scope; |
||||
} |
||||
} |
||||
|
||||
function flattenScope(scope: Scope): Record<string, Definition> { |
||||
return Object.fromEntries( |
||||
Object.entries(scope).flatMap(([k, fn]) => { |
||||
const v = fn(); |
||||
if ('definition' in v) { |
||||
return [[k, v.definition] as const]; |
||||
} else { |
||||
return Object.entries(mapKeys(flattenScope(v.namespace), k2 => k + '.' + k2)); |
||||
} |
||||
}), |
||||
); |
||||
} |
||||
@ -0,0 +1,37 @@ |
||||
import { useState } from "react"; |
||||
|
||||
export function useLocalStorage(key: string, initialValue: any) { |
||||
// State to store our value
|
||||
// Pass initial state function to useState so logic is only executed once
|
||||
const [storedValue, setStoredValue] = useState(() => { |
||||
try { |
||||
// Get from local storage by key
|
||||
const item = window.localStorage.getItem(key); |
||||
// Parse stored json or if none return initialValue
|
||||
return item ? JSON.parse(item) : initialValue; |
||||
} catch (error) { |
||||
// If error also return initialValue
|
||||
console.log(error); |
||||
return initialValue; |
||||
} |
||||
}); |
||||
|
||||
// Return a wrapped version of useState's setter function that ...
|
||||
// ... persists the new value to localStorage.
|
||||
const setValue = (value: any) => { |
||||
try { |
||||
// Allow value to be a function so we have same API as useState
|
||||
const valueToStore = |
||||
value instanceof Function ? value(storedValue) : value; |
||||
// Save state
|
||||
setStoredValue(valueToStore); |
||||
// Save to local storage
|
||||
window.localStorage.setItem(key, JSON.stringify(valueToStore)); |
||||
} catch (error) { |
||||
// A more advanced implementation would handle the error case
|
||||
console.log(error); |
||||
} |
||||
}; |
||||
|
||||
return [storedValue, setValue]; |
||||
} |
||||
@ -0,0 +1,31 @@ |
||||
import React from "react"; |
||||
|
||||
export const ErrorView: React.FC = () => { |
||||
return ( |
||||
<div |
||||
style={{ |
||||
width: "100%", |
||||
display: "flex", |
||||
flexDirection: "column", |
||||
alignItems: "center", |
||||
}} |
||||
> |
||||
<img |
||||
style={{ paddingBottom: "2em" }} |
||||
width="250" |
||||
src="https://res.cloudinary.com/key-solutions/image/upload/v1580400635/solid/error-png.png" |
||||
alt="Error page" |
||||
/> |
||||
<h5>Sorry, something unexpected happened. </h5> |
||||
<h5> |
||||
Please raise an issue:{" "} |
||||
<a |
||||
style={{ color: "red" }} |
||||
href="https://github.com/Machinalabs/remix-ethdoc-plugin/issues" |
||||
> |
||||
Here |
||||
</a> |
||||
</h5> |
||||
</div> |
||||
); |
||||
}; |
||||
@ -0,0 +1 @@ |
||||
|
||||
|
After Width: | Height: | Size: 3.1 KiB |
@ -0,0 +1,13 @@ |
||||
<!DOCTYPE html> |
||||
<html lang="en"> |
||||
<head> |
||||
<meta charset="utf-8" /> |
||||
<title>Documentation generator</title> |
||||
<base href="/" /> |
||||
<meta name="viewport" content="width=device-width, initial-scale=1" /> |
||||
<link rel="icon" type="image/x-icon" href="favicon.ico" /> |
||||
</head> |
||||
<body> |
||||
<div id="root"></div> |
||||
</body> |
||||
</html> |
||||
@ -0,0 +1,11 @@ |
||||
import React from "react"; |
||||
import ReactDOM from "react-dom"; |
||||
import App from "./app/App"; |
||||
// import { Routes } from "./routes";
|
||||
|
||||
ReactDOM.render( |
||||
<React.StrictMode> |
||||
<App /> |
||||
</React.StrictMode>, |
||||
document.getElementById("root") |
||||
); |
||||
@ -0,0 +1,17 @@ |
||||
{ |
||||
"name": "doc-gen", |
||||
"displayName": "Docgen - Documentation Generator", |
||||
"description": "Generate Solidity documentation (as md)", |
||||
"version": "0.1.0", |
||||
"events": [], |
||||
"methods": ["generateDocs", "openDocs"], |
||||
"kind": "none", |
||||
"icon": "data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiA/PjxzdmcgaGVpZ2h0PSIxMDI0IiB3aWR0aD0iMTAyNCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBkPSJNOTUwLjE1NCAxOTJINzMuODQ2QzMzLjEyNyAxOTIgMCAyMjUuMTI2OTk5OTk5OTk5OTUgMCAyNjUuODQ2djQ5Mi4zMDhDMCA3OTguODc1IDMzLjEyNyA4MzIgNzMuODQ2IDgzMmg4NzYuMzA4YzQwLjcyMSAwIDczLjg0Ni0zMy4xMjUgNzMuODQ2LTczLjg0NlYyNjUuODQ2QzEwMjQgMjI1LjEyNjk5OTk5OTk5OTk1IDk5MC44NzUgMTkyIDk1MC4xNTQgMTkyek01NzYgNzAzLjg3NUw0NDggNzA0VjUxMmwtOTYgMTIzLjA3N0wyNTYgNTEydjE5MkgxMjhWMzIwaDEyOGw5NiAxMjggOTYtMTI4IDEyOC0wLjEyNVY3MDMuODc1ek03NjcuMDkxIDczNS44NzVMNjA4IDUxMmg5NlYzMjBoMTI4djE5Mmg5Nkw3NjcuMDkxIDczNS44NzV6Ii8+PC9zdmc+", |
||||
"location": "sidePanel", |
||||
"documentation": "", |
||||
"repo": "https://github.com/ethereum/remix-project/", |
||||
"maintainedBy": "", |
||||
"authorContact": "", |
||||
"url": "", |
||||
"targets":["remix"] |
||||
} |
||||
@ -0,0 +1,11 @@ |
||||
export type Documentation = string |
||||
|
||||
export interface EthDocumentation { |
||||
[contractName: string]: Documentation |
||||
} |
||||
|
||||
export type ContractName = string |
||||
|
||||
export type FileName = string |
||||
|
||||
export type PublishedSite = string |
||||
@ -0,0 +1,23 @@ |
||||
{ |
||||
"extends": "./tsconfig.json", |
||||
"compilerOptions": { |
||||
"outDir": "../../dist/out-tsc", |
||||
"types": ["node"] |
||||
}, |
||||
"files": [ |
||||
"../../node_modules/@nrwl/react/typings/cssmodule.d.ts", |
||||
"../../node_modules/@nrwl/react/typings/image.d.ts" |
||||
], |
||||
"exclude": [ |
||||
"jest.config.ts", |
||||
"**/*.spec.ts", |
||||
"**/*.test.ts", |
||||
"**/*.spec.tsx", |
||||
"**/*.test.tsx", |
||||
"**/*.spec.js", |
||||
"**/*.test.js", |
||||
"**/*.spec.jsx", |
||||
"**/*.test.jsx" |
||||
], |
||||
"include": ["**/*.js", "**/*.jsx", "**/*.ts", "**/*.tsx"] |
||||
} |
||||
@ -0,0 +1,16 @@ |
||||
{ |
||||
"extends": "../../tsconfig.base.json", |
||||
"compilerOptions": { |
||||
"jsx": "react-jsx", |
||||
"allowJs": true, |
||||
"esModuleInterop": true, |
||||
"allowSyntheticDefaultImports": true |
||||
}, |
||||
"files": [], |
||||
"include": [], |
||||
"references": [ |
||||
{ |
||||
"path": "./tsconfig.app.json" |
||||
} |
||||
] |
||||
} |
||||
@ -0,0 +1,73 @@ |
||||
const { composePlugins, withNx } = require('@nrwl/webpack') |
||||
const { withReact } = require('@nrwl/react') |
||||
const webpack = require('webpack') |
||||
const TerserPlugin = require("terser-webpack-plugin") |
||||
const CssMinimizerPlugin = require("css-minimizer-webpack-plugin") |
||||
|
||||
// Nx plugins for webpack.
|
||||
module.exports = composePlugins(withNx(), withReact(), (config) => { |
||||
// Update the webpack config as needed here.
|
||||
// e.g. `config.plugins.push(new MyPlugin())`
|
||||
|
||||
// add fallback for node modules
|
||||
config.resolve.fallback = { |
||||
...config.resolve.fallback, |
||||
"path": require.resolve("path-browserify"), |
||||
"fs": false, |
||||
} |
||||
|
||||
// add externals
|
||||
config.externals = { |
||||
...config.externals, |
||||
solc: 'solc', |
||||
} |
||||
|
||||
config.module.rules.push({ |
||||
test: /\.hbs$/, |
||||
type: 'asset/source' |
||||
}) |
||||
|
||||
|
||||
// add public path
|
||||
config.output.publicPath = '/' |
||||
|
||||
// add copy & provide plugin
|
||||
config.plugins.push( |
||||
new webpack.ProvidePlugin({ |
||||
Buffer: ['buffer', 'Buffer'], |
||||
url: ['url', 'URL'], |
||||
process: 'process/browser', |
||||
}), |
||||
new webpack.DefinePlugin({ |
||||
|
||||
}), |
||||
) |
||||
|
||||
// souce-map loader
|
||||
config.module.rules.push({ |
||||
test: /\.js$/, |
||||
use: ["source-map-loader"], |
||||
enforce: "pre" |
||||
}) |
||||
|
||||
config.ignoreWarnings = [/Failed to parse source map/] // ignore source-map-loader warnings
|
||||
|
||||
// set minimizer
|
||||
config.optimization.minimizer = [ |
||||
new TerserPlugin({ |
||||
parallel: true, |
||||
terserOptions: { |
||||
ecma: 2015, |
||||
compress: false, |
||||
mangle: false, |
||||
format: { |
||||
comments: false, |
||||
}, |
||||
}, |
||||
extractComments: false, |
||||
}), |
||||
new CssMinimizerPlugin(), |
||||
]; |
||||
|
||||
return config; |
||||
}) |
||||
@ -0,0 +1,61 @@ |
||||
{ |
||||
"name": "doc-viewer", |
||||
"$schema": "../../node_modules/nx/schemas/project-schema.json", |
||||
"sourceRoot": "apps/doc-viewer/src", |
||||
"projectType": "application", |
||||
"implicitDependencies": [ |
||||
], |
||||
"targets": { |
||||
"build": { |
||||
"executor": "@nrwl/webpack:webpack", |
||||
"outputs": ["{options.outputPath}"], |
||||
"defaultConfiguration": "development", |
||||
"options": { |
||||
"compiler": "babel", |
||||
"outputPath": "dist/apps/doc-viewer", |
||||
"index": "apps/doc-viewer/src/index.html", |
||||
"baseHref": "./", |
||||
"main": "apps/doc-viewer/src/main.tsx", |
||||
"tsConfig": "apps/doc-viewer/tsconfig.app.json", |
||||
"assets": [ |
||||
"apps/doc-viewer/src/favicon.ico", |
||||
"apps/doc-viewer/src/profile.json" |
||||
], |
||||
"styles": [], |
||||
"scripts": [], |
||||
"webpackConfig": "apps/doc-viewer/webpack.config.js" |
||||
}, |
||||
"configurations": { |
||||
"development": { |
||||
}, |
||||
"production": { |
||||
"fileReplacements": [ |
||||
{ |
||||
"replace": "apps/doc-viewer/src/environments/environment.ts", |
||||
"with": "apps/doc-viewer/src/environments/environment.prod.ts" |
||||
} |
||||
] |
||||
} |
||||
} |
||||
}, |
||||
"serve": { |
||||
"executor": "@nrwl/webpack:dev-server", |
||||
"defaultConfiguration": "development", |
||||
"options": { |
||||
"buildTarget": "doc-viewer:build", |
||||
"hmr": true, |
||||
"baseHref": "/" |
||||
}, |
||||
"configurations": { |
||||
"development": { |
||||
"buildTarget": "doc-viewer:build:development", |
||||
"port": 7003 |
||||
}, |
||||
"production": { |
||||
"buildTarget": "doc-viewer:build:production" |
||||
} |
||||
} |
||||
} |
||||
}, |
||||
"tags": [] |
||||
} |
||||
@ -0,0 +1,23 @@ |
||||
import React, { useEffect, useState } from "react" |
||||
import { DocViewer } from "./docviewer" |
||||
import ReactMarkdown from 'react-markdown' |
||||
import remarkGfm from 'remark-gfm' |
||||
|
||||
const client = new DocViewer() |
||||
|
||||
export default function App() { |
||||
const [contents, setContents] = useState('') |
||||
useEffect(() => { |
||||
client.eventEmitter.on('contentsReady', (fileContents: string) => { |
||||
setContents(fileContents) |
||||
}) |
||||
|
||||
}, []) |
||||
return ( |
||||
<> |
||||
<div className="m-5 p-2"> |
||||
<ReactMarkdown children={contents} remarkPlugins={[remarkGfm]}/> |
||||
</div> |
||||
</> |
||||
) |
||||
} |
||||
@ -0,0 +1,22 @@ |
||||
import { PluginClient } from '@remixproject/plugin' |
||||
import { createClient } from '@remixproject/plugin-webview' |
||||
import EventEmitter from 'events' |
||||
|
||||
export class DocViewer extends PluginClient { |
||||
mdFile: string |
||||
eventEmitter: EventEmitter |
||||
constructor() { |
||||
super() |
||||
this.eventEmitter = new EventEmitter() |
||||
this.methods = ['viewDocs'] |
||||
createClient(this) |
||||
this.mdFile = '' |
||||
this.onload() |
||||
} |
||||
|
||||
async viewDocs(docs: string[]) { |
||||
this.mdFile = docs[0] |
||||
const contents = await this.call('fileManager', 'readFile', this.mdFile) |
||||
this.eventEmitter.emit('contentsReady', contents) |
||||
} |
||||
} |
||||
|
After Width: | Height: | Size: 3.1 KiB |
@ -0,0 +1,13 @@ |
||||
<!DOCTYPE html> |
||||
<html lang="en"> |
||||
<head> |
||||
<meta charset="utf-8" /> |
||||
<title>Doc Viewer</title> |
||||
<base href="/" /> |
||||
<meta name="viewport" content="width=device-width, initial-scale=1" /> |
||||
<link rel="icon" type="image/x-icon" href="favicon.ico" /> |
||||
</head> |
||||
<body> |
||||
<div id="root"></div> |
||||
</body> |
||||
</html> |
||||
@ -0,0 +1,10 @@ |
||||
import React from 'react' |
||||
import ReactDOM from 'react-dom' |
||||
import App from './app/App' |
||||
|
||||
ReactDOM.render( |
||||
<React.StrictMode> |
||||
<App /> |
||||
</React.StrictMode>, |
||||
document.getElementById("root") |
||||
); |
||||
@ -0,0 +1,16 @@ |
||||
{ |
||||
"name": "doc-viewer", |
||||
"displayName": "Docgen Viewer", |
||||
"description": "Visualize Solidity documentation from Docgen Plugin", |
||||
"version": "0.1.0", |
||||
"events": [], |
||||
"methods": ["viewDoc"], |
||||
"kind": "none", |
||||
"icon": "data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiA/PjxzdmcgaGVpZ2h0PSIxMDI0IiB3aWR0aD0iMTAyNCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBkPSJNOTUwLjE1NCAxOTJINzMuODQ2QzMzLjEyNyAxOTIgMCAyMjUuMTI2OTk5OTk5OTk5OTUgMCAyNjUuODQ2djQ5Mi4zMDhDMCA3OTguODc1IDMzLjEyNyA4MzIgNzMuODQ2IDgzMmg4NzYuMzA4YzQwLjcyMSAwIDczLjg0Ni0zMy4xMjUgNzMuODQ2LTczLjg0NlYyNjUuODQ2QzEwMjQgMjI1LjEyNjk5OTk5OTk5OTk1IDk5MC44NzUgMTkyIDk1MC4xNTQgMTkyek01NzYgNzAzLjg3NUw0NDggNzA0VjUxMmwtOTYgMTIzLjA3N0wyNTYgNTEydjE5MkgxMjhWMzIwaDEyOGw5NiAxMjggOTYtMTI4IDEyOC0wLjEyNVY3MDMuODc1ek03NjcuMDkxIDczNS44NzVMNjA4IDUxMmg5NlYzMjBoMTI4djE5Mmg5Nkw3NjcuMDkxIDczNS44NzV6Ii8+PC9zdmc+", |
||||
"location": "mainPanel", |
||||
"url": "", |
||||
"documentation": "https://remix-plugins.readthedocs.io/en/latest/", |
||||
"repo": "https://github.com/Machinalabs/remix-ethdoc-plugin/", |
||||
"maintainedBy": "Remix", |
||||
"authorContact": "remix@ethereum.org" |
||||
} |
||||
@ -0,0 +1,23 @@ |
||||
{ |
||||
"extends": "./tsconfig.json", |
||||
"compilerOptions": { |
||||
"outDir": "../../dist/out-tsc", |
||||
"types": ["node"] |
||||
}, |
||||
"files": [ |
||||
"../../node_modules/@nrwl/react/typings/cssmodule.d.ts", |
||||
"../../node_modules/@nrwl/react/typings/image.d.ts" |
||||
], |
||||
"exclude": [ |
||||
"jest.config.ts", |
||||
"**/*.spec.ts", |
||||
"**/*.test.ts", |
||||
"**/*.spec.tsx", |
||||
"**/*.test.tsx", |
||||
"**/*.spec.js", |
||||
"**/*.test.js", |
||||
"**/*.spec.jsx", |
||||
"**/*.test.jsx" |
||||
], |
||||
"include": ["**/*.js", "**/*.jsx", "**/*.ts", "**/*.tsx"] |
||||
} |
||||
@ -0,0 +1,16 @@ |
||||
{ |
||||
"extends": "../../tsconfig.base.json", |
||||
"compilerOptions": { |
||||
"jsx": "react-jsx", |
||||
"allowJs": true, |
||||
"esModuleInterop": true, |
||||
"allowSyntheticDefaultImports": true |
||||
}, |
||||
"files": [], |
||||
"include": [], |
||||
"references": [ |
||||
{ |
||||
"path": "./tsconfig.app.json" |
||||
} |
||||
] |
||||
} |
||||
@ -0,0 +1,60 @@ |
||||
const { composePlugins, withNx } = require('@nrwl/webpack') |
||||
const { withReact } = require('@nrwl/react') |
||||
const webpack = require('webpack') |
||||
const TerserPlugin = require("terser-webpack-plugin") |
||||
const CssMinimizerPlugin = require("css-minimizer-webpack-plugin") |
||||
|
||||
// Nx plugins for webpack.
|
||||
module.exports = composePlugins(withNx(), withReact(), (config) => { |
||||
// Update the webpack config as needed here.
|
||||
// e.g. `config.plugins.push(new MyPlugin())`
|
||||
|
||||
// add externals
|
||||
config.externals = { |
||||
...config.externals, |
||||
solc: 'solc', |
||||
} |
||||
|
||||
// add public path
|
||||
config.output.publicPath = '/' |
||||
|
||||
// add copy & provide plugin
|
||||
config.plugins.push( |
||||
new webpack.ProvidePlugin({ |
||||
Buffer: ['buffer', 'Buffer'], |
||||
url: ['url', 'URL'], |
||||
process: 'process/browser', |
||||
}), |
||||
new webpack.DefinePlugin({ |
||||
|
||||
}), |
||||
) |
||||
|
||||
// souce-map loader
|
||||
config.module.rules.push({ |
||||
test: /\.js$/, |
||||
use: ["source-map-loader"], |
||||
enforce: "pre" |
||||
}) |
||||
|
||||
config.ignoreWarnings = [/Failed to parse source map/] // ignore source-map-loader warnings
|
||||
|
||||
// set minimizer
|
||||
config.optimization.minimizer = [ |
||||
new TerserPlugin({ |
||||
parallel: true, |
||||
terserOptions: { |
||||
ecma: 2015, |
||||
compress: false, |
||||
mangle: false, |
||||
format: { |
||||
comments: false, |
||||
}, |
||||
}, |
||||
extractComments: false, |
||||
}), |
||||
new CssMinimizerPlugin(), |
||||
]; |
||||
|
||||
return config; |
||||
}) |
||||
@ -1,6 +1,9 @@ |
||||
export type ReceiptStatus = "Verified" | "Queue" |
||||
export type ReceiptStatus = "Pending in queue" | "Pass - Verified" | "Already Verified" | "Max rate limit reached" | "Successfully Updated" |
||||
|
||||
export interface Receipt { |
||||
guid: string |
||||
status: ReceiptStatus |
||||
isProxyContract: boolean |
||||
message?: string |
||||
succeed?: boolean |
||||
} |
||||
|
||||
@ -0,0 +1,36 @@ |
||||
export const scanAPIurls = { |
||||
// all mainnet
|
||||
1: "https://api.etherscan.io/api", |
||||
56: "https://api.bscscan.com/api", |
||||
137: "https://api.polygonscan.com/api", |
||||
250: "https://api.ftmscan.com/api", |
||||
42161: "https://api.arbiscan.io/api", |
||||
43114: "https://api.snowtrace.io/api", |
||||
1285: "https://api-moonriver.moonscan.io/api", |
||||
1284: "https://api-moonbeam.moonscan.io/api", |
||||
25: "https://api.cronoscan.com/api", |
||||
199: "https://api.bttcscan.com/api", |
||||
10: "https://api-optimistic.etherscan.io/api", |
||||
42220: "https://api.celoscan.io/api", |
||||
288: "https://api.bobascan.com/api", |
||||
100: "https://api.gnosisscan.io/api", |
||||
1101: "https://api-zkevm.polygonscan.com/api", |
||||
|
||||
// all testnet
|
||||
5: "https://api-goerli.etherscan.io/api", |
||||
11155111: "https://api-sepolia.etherscan.io/api", |
||||
97: "https://api-testnet.bscscan.com/api", |
||||
80001: "https://api-testnet.polygonscan.com/api", |
||||
4002: "https://api-testnet.ftmscan.com/api", |
||||
421611: "https://api-testnet.arbiscan.io/api", |
||||
42170: "https://api-nova.arbiscan.io/api", |
||||
43113: "https://api-testnet.snowtrace.io/api", |
||||
1287: "https://api-moonbase.moonscan.io/api", |
||||
338: "https://api-testnet.cronoscan.com/api", |
||||
1028: "https://api-testnet.bttcscan.com/api", |
||||
420: "https://api-goerli-optimistic.etherscan.io/api", |
||||
44787: "https://api-alfajores.celoscan.io/api", |
||||
2888: "https://api-testnet.bobascan.com/api", |
||||
84531: "https://api-goerli.basescan.org/api", |
||||
1442: "https://api-testnet-zkevm.polygonscan.com/api" |
||||
} |
||||
@ -1,25 +1,30 @@ |
||||
export const verifyScript = ` |
||||
/** |
||||
* @param {string} apikey - etherscan api key. |
||||
* @param {string} contractAddress - Address of the contract to verify. |
||||
* @param {string} contractArguments - Parameters used in the contract constructor during the initial deployment. It should be the hex encoded value. |
||||
* @param {string} apikey - etherscan api key |
||||
* @param {string} contractAddress - Address of the contract to verify |
||||
* @param {string} contractArguments - Parameters used in the contract constructor during the initial deployment. It should be the hex encoded value |
||||
* @param {string} contractName - Name of the contract |
||||
* @param {string} contractFile - File where the contract is located |
||||
* @param {number | string} chainRef - Network chain id or API URL (optional) |
||||
* @param {boolean} isProxyContract - true, if contract is a proxy contract (optional) |
||||
* @param {string} expectedImplAddress - Implementation contract address, in case of proxy contract verification (optional) |
||||
* @returns {{ guid, status, message, succeed }} verification result |
||||
*/ |
||||
export const verify = async (apikey: string, contractAddress: string, contractArguments: string, contractName: string, contractFile: string) => { |
||||
export const verify = async (apikey: string, contractAddress: string, contractArguments: string, contractName: string, contractFile: string, chainRef?: number | string, isProxyContract?: boolean, expectedImplAddress?: string) => { |
||||
const compilationResultParam = await remix.call('compilerArtefacts' as any, 'getCompilerAbstract', contractFile) |
||||
console.log('verifying.. ' + contractName) |
||||
return await remix.call('etherscan' as any, 'verify', apikey, contractAddress, contractArguments, contractName, compilationResultParam) |
||||
// update apiKey and chainRef to verify contract on multiple networks
|
||||
return await remix.call('etherscan' as any, 'verify', apikey, contractAddress, contractArguments, contractName, compilationResultParam, chainRef, isProxyContract, expectedImplAddress) |
||||
}` |
||||
|
||||
export const receiptGuidScript = ` |
||||
/** |
||||
* @param {string} apikey - etherscan api key. |
||||
* @param {string} guid - receipt id. |
||||
* @param {string} apikey - etherscan api key |
||||
* @param {string} guid - receipt id |
||||
* @param {boolean} isProxyContract - true, if contract is a proxy contract (optional) |
||||
* @returns {{ status, message, succeed }} receiptStatus |
||||
*/ |
||||
export const receiptStatus = async (apikey: string, guid: string) => { |
||||
return await remix.call('etherscan' as any, 'receiptStatus', guid, apikey) |
||||
export const receiptStatus = async (apikey: string, guid: string, isProxyContract?: boolean) => { |
||||
return await remix.call('etherscan' as any, 'receiptStatus', guid, apikey, isProxyContract) |
||||
} |
||||
` |
||||
@ -0,0 +1,16 @@ |
||||
{ |
||||
"name": "etherscan", |
||||
"displayName": "Contract verification - Etherscan", |
||||
"description": "Verify Solidity contract code using Etherscan, BscScan, PolygonScan etc. APIs", |
||||
"version": "0.1.0", |
||||
"events": [], |
||||
"methods": ["verify", "receiptStatus"], |
||||
"kind": "none", |
||||
"icon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAHsAAAB7CAYAAABUx/9/AAAABmJLR0QAAAAAAAD5Q7t/AAAACXBIWXMAAAsTAAALEwEAmpwYAAAHBklEQVR42u2dy3WbTBTH/+ikgFEFwZ8K8HQAm6yjDkIHdiogHWBXgDqADgQVaLLJToZ1NtAB38JC0QNJIPGYx73nsIgcHVvz033OnblWVVXQQcqyhBACQgiUZYk0TfHnz5/q79+/rd7PGPsA8I1z/gEAjuOAMQbOOVzX1WKNLFVhCyGQJAnSNEUcx0N/CMu2bXDO4TgOXNcF51y9RauqSomnKApEUQTG2BZANeXDGNsyxuB5HqIoUmYNpf8DoyjC1HBbPEqAl/KPyrJMCg2+V+N930eWZQT72rNer6Ea4FvavtlsCLbGkM+gu66L9XptNuwsy3SG3KjpU5r3ySJrgyCfQfd93wzYmpvs1sBt2x7dtJM2S2DatYJN2nxby8eI2of/BQSzNfQgCNSETWb7PuDL5VIt2IalVL0D55wPwmXW98bKfD7fPj096bFvOtHeVJ7n2/l8DiGEvLteKtazZa+z9xm4EWiDgBNog4ATaIOAE2iDgFMebVBadnfDoWVZlF5N1CTKOcdms+n8xhmBVi8PF0Lg58+fw+fZZErlMeldGxwpIFM8YOvS+UJarUF/W++waWGbNSuKoof6ynpom269NUrme0SfOYQydTHnpNUPwO6zU3QMc06gH1hgyTp6blqam0UVyqkvL02fJ2B7WGfLtu26caR7UYVAK9f0gLe3t+7fzvl8vi3L8j9aQ2U0u75QYLHbt2hfQSOfrJzPvnni5OK3k0y4epp9y3fPCLSevnu1WrX7dhJspTX74jbojEDruw162oo8o3XRV97f3y+bIkq3tDHjzWmYhukWPM976Oxzy50oFQ5AIgzD5to4DG/I6whACdiHBwVnhyZcB9uq5M2DAwljbJskyXmApouv/vr1K1E+YFqWJeI4pmjcFEnTlGCbInmeAwC+UCFFa5/9AaC+//UTNom2PntxWDIlM65x0ScMw6PshGBrCtr3fXied/QiwdYQtOd5+PXr19kPZhSc6QXadV2EYdj4wykCNItzDs555wLI+/s7bdTcWNfdbZIXRam7Om9sUPR64y/UqY232hMY3Wf/+PHjofcXRbEgJT7X6DaH80eHrcuMLNVAUzRuEGiCbRBogm0Q6Le3N6qNmwB6V0uxSLMVK5jcCZrMuEqg6ybKLnLaakawFQDt+/7FEug10KfVRvLZkkrd9x0EwdnuVRtpKisTbIlBr9fru7plL21uEWwJzXY9+umuN1/ZxSSfLRno19fXQUCTZkskVVVZcRxjuVwOApo0WzIZEjTB1sHud+g0mlVVZdGSaQ/a4pyTZpug0cDncFeCbQBoAHh+fibYJoAGPjuECLYikuf5Q2fyOOefeXZVVRb1j8srD951Y3HOwRgjzdYc9N6EA1RB09I/n4rjOJ95dv1CfZaXRB/QjLEPxti+MreHTc33+ml0WZaLwz598tl3sPA8z7p2Y/9UEXeTfP/+/d8/Rp7yM/S5qCHPesHzvF6HwAy59vVUoKIo9r/jKEArimJBKdixzwOweHl5aTzvLJvZPjXhnueBMbZ/jaLxKzJGHDOkcp0eojzz2bQLNo4kSTIkaItzfnaIkjRb4Wj7mry8vJy91hiNk3YPI0NE203fJdu2G9uPSbNHkjHvcr904cGXa5Eo3V+ijtk+yB7w+vraDbZqaVj9QW3bNlKb63QrCIKjdOvoSzfyLM5eRi3UR1Bt2wbnHI7jwHVdae4az/McT09PYyvKzVmcSvrsLMss2bR4Km0+lCAIrv+HsUcHDlFqlOHZHaedbFxGL/Oze67bagd5ZzYnm4tS18Db1OxbmfGiKBZxHO/nRDHG8Pz8fC1YOvKftm1LaXJVibJvBWW+77da315nU1HOPP73zXXd1jcy0H52B1mtVrAsq5IBdN2F0ulGBl0Dpj6f3YJKN8PscEBbq0CbYCoHuaqrZF0/D/lsuX1yo5++5y408tknVa/5fL6VxSdfq5J1vSKLfLb8proxn95sNvf31JkIuOUUXa1AGwd7VztWanJwX6CNgK2KmR4atJawsyxTUoOHBq0N7CiK6u6MSodnCNDKwtYNLhom+Qxx8kT65oUkSSCEwO/fv7FarXSvAFnL5RJhGF5sLXpEpICd5znyPIcQAmVZIk1TJEliWmnPCoLgYrOgUrCTJEGSJAD+TWo3EOjFqlgYhsOPwRrT12rqYx+eYHh40nLQ9TesV0sayHWNe1RlmyqiNhm07/ujabM0qdfUzXpTmOyhDvMrk2fv9ma1hVz3iU29ztSWO7Am910F066ClmUZfN9XdofK9/1JzbWy5dIoilSAjuVyiSiKpF5L5WriMjQd1BrseR6iKJoksr7nUbbhUAiBJEmQpiniOB7lNgMZT4x2+hA6dZfWmyZ1fV0I0bpLtL4Gq4boOM7+GFN9q6/q8j8QmqQtM04gOgAAAABJRU5ErkJggg==", |
||||
"location": "sidePanel", |
||||
"url": "https://ipfs-cluster.ethdevops.io/ipfs/QmQsZbBSYCVBVpz2mVRbPRVTrcz59oJEpuuoxiT9otu3mh", |
||||
"repo": "https://github.com/ethereum/remix-project/tree/master/apps/etherscan", |
||||
"documentation": "https://remix-etherscan-plugin.readthedocs.io/en/latest", |
||||
"maintainedBy": "Remix", |
||||
"authorContact": "remix@ethereum.org" |
||||
} |
||||
@ -0,0 +1,23 @@ |
||||
{ |
||||
"name": "remix-ide-e2e", |
||||
"license": "MIT", |
||||
"engines": { |
||||
"node": "^20.0.0", |
||||
"npm": "^6.14.15" |
||||
}, |
||||
"dependencies": { |
||||
"@openzeppelin/contracts": "^4.8.3", |
||||
"@openzeppelin/contracts-upgradeable": "^4.8.3", |
||||
"@openzeppelin/upgrades-core": "^1.22.0", |
||||
"@openzeppelin/wizard": "^0.1.1", |
||||
"@remix-project/remixd": "../../dist/libs/remixd", |
||||
"deep-equal": "^1.0.1", |
||||
"ganache-cli": "^6.8.1", |
||||
"selenium-standalone": "^8.2.3", |
||||
"tree-kill": "^1.2.2" |
||||
}, |
||||
"devDependencies": { |
||||
"http-server": "^14.1.1", |
||||
"nightwatch": "2.3" |
||||
} |
||||
} |
||||
@ -1,4 +1,9 @@ |
||||
{ |
||||
"presets": ["@nrwl/react/babel"], |
||||
"plugins": [] |
||||
"presets": ["@babel/preset-env", ["@babel/preset-react", |
||||
{"runtime": "automatic"} |
||||
]], |
||||
"plugins": ["@babel/plugin-proposal-class-properties", "@babel/plugin-transform-runtime", "@babel/plugin-proposal-nullish-coalescing-operator"], |
||||
"ignore": [ |
||||
"**/node_modules/**" |
||||
] |
||||
} |
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in new issue