Skip to content

Commit

Permalink
T
Browse files Browse the repository at this point in the history
  • Loading branch information
@Vectorized
Vectorized committed Dec 24, 2024
1 parent cb13e82 commit a5b0222
Showing 1 changed file with 32 additions and 35 deletions.
67 changes: 32 additions & 35 deletions prep/gen-docs.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,23 +30,22 @@ async function main() {

const strip = s => s.replace(/^\s+|\s+$/g, '');

const toHeaderCase = str =>
strip(str)
const toHeaderCase = str => strip(str)
.toLowerCase()
.replace(/(eth|sha|lz|uups|(eip|rip|erc|push|create)\-?[0-9]+i?)/g, m => m.toUpperCase())
.split(/\s+/)
.map(w => w.replace(/^([a-zA-Z])/, c => c.toUpperCase()))
.join(' ');

const deindent = s => s.split('\n').map(l => l.replace(/^\s{4}/g, '')).join('\n');
const deindent = s => s.replace(/^ {4}/gm, '');

const getFunctionSig = s => coalesce(
s.match(/(\w+)\s*\(([^)]*)\)/),
m => m[1] + '(' + m[2].split(',').map(x => strip(x).split(/\s+/)[0]) + ')'
);

const cleanNatspecOrNote = s => deindent(strip(
s.replace(/\s+\/\/\/?/g, '\n').replace(/\s?\n\s?/g, ' \n')
const cleanNatspecOrNote = s => deindent(strip(s
.replace(/\s+\/\/\/?/g, '\n').replace(/\s?\n\s?/g, ' \n')
.replace(/```([\s\S]+?)```/g, '```solidity$1```')
.replace(/^\/\/\/\s+@[a-z]+\s?/, '')
));
Expand All @@ -57,19 +56,19 @@ async function main() {
for (let m = null; (m = sectionHeaderRe.exec(s)) !== null; l = m) {
if (l !== null) {
a.push({
header: toHeaderCase(l[1]),
h2: toHeaderCase(l[1]),
src: s.slice(l.index + l[0].length, m.index)
});
}
}
if (l !== null) {
a.push({
header: toHeaderCase(l[1]),
h2: toHeaderCase(l[1]),
src: s.slice(l.index + l[0].length)
});
}
return a
.filter(x => !has(x.header, 'private'))
.filter(x => !has(x.h2, 'private'))
.map(item => {
const m = (/^((\s+\/\/\s[^\n]+)+)/).exec(item.src);
if (m) item.note = cleanNatspecOrNote(m[0]);
Expand All @@ -90,31 +89,31 @@ async function main() {
.map(m => ({
natspec: cleanNatspecOrNote(m[1]),
def: deindent(strip(m[2])),
title: getFunctionSig(deindent(strip(m[2])))
h3: getFunctionSig(deindent(strip(m[2])))
}));

const getConstantsAndImmutables = s =>
getSubSections(s, /((?:\/\/\/\s[^\n]+\n\s*?)+)((?:bytes|uint|address)[0-9]*\s+(?:public|internal)\s+(?:immutable|constant)\s+([A-Za-z0-9_]+)[^;]*)/g)
.map(m => ({
natspec: cleanNatspecOrNote(m[1]),
def: deindent(strip(m[2])),
title: deindent(strip(m[3]))
h3: deindent(strip(m[3]))
}));

const getCustomErrors = s =>
getSubSections(s, /((?:\/\/\/\s[^\n]+\n\s*?)+)(error\s[^;]+);/g)
.map(m => ({
natspec: cleanNatspecOrNote(m[1]),
def: deindent(strip(m[2])),
title: getFunctionSig(deindent(strip(m[2])))
h3: getFunctionSig(deindent(strip(m[2])))
}));

const getStructsAndEnums = s =>
getSubSections(s, /((?:\/\/\/\s[^\n]+\n\s*?)+)((?:struct|enum)\s([A-Za-z0-9_]+)\s+\{[^}]+})/g)
.map(m => ({
natspec: cleanNatspecOrNote(m[1]),
def: deindent(strip(m[2])),
title: deindent(strip(m[3]))
h3: deindent(strip(m[3]))
}));

const getNotice = s => coalesce(
Expand All @@ -126,8 +125,8 @@ async function main() {
const r = /import\s[\s\S]*?(["'][\s\S]+?["'])/g;
let a = [];
for (let m = null; (m = r.exec(s)) !== null; ) {
a.push(path.normalize(path.dirname(srcPath) + path.sep + m[1].slice(1, -1))
.split(path.sep).slice(-2).join(path.sep));
const p = path.normalize(path.dirname(srcPath) + path.sep + m[1].slice(1, -1));
a.push(p.split(path.sep).slice(-2).join(path.sep));
}
return a;
};
Expand All @@ -136,8 +135,8 @@ async function main() {
s.match(/\/\/\/\s+@notice\s+[\s\S]+?(?:\/\/\/\s?@author\s+[\s\S]+?\n|\/\/\/\s+\([\s\S]+?\)\n)+([\s\S]*?)(?:library|(?:abstract\s+?)contract)\s[\s\S]+?\{/),
m => strip(
m[1].split('\n')
.map(l =>
l.replace(/^\/\/\/\s*/, '')
.map(l => l
.replace(/^\/\/\/\s*/, '')
.replace(/^@dev\s?([\s\S]+?)\:/, '$1:\n\n')
.replace(/^Note\:/, 'Note:\n\n')
.replace(/^[\s\S]{1,64}\:/, m => has(m, 'http') ? m : '<b>' + m + '</b>')
Expand Down Expand Up @@ -182,26 +181,24 @@ async function main() {
}

const docHeader = '# ' + getTitle(srcPath) + '\n\n' + getNotice(src);
let writeDoc = false;
let docChunks = [];
sections.forEach(x => {
let a = getStructsAndEnums(x.src);
if (a.length < 1) a = getCustomErrors(x.src);
if (a.length < 1) a = getFunctionsAndModifiers(x.src);
if (a.length < 1) a = getConstantsAndImmutables(x.src);
if (a.length > 0) {
writeDoc = true;
docChunks.push('## ' + x.header);
if (a.length) {
docChunks.push('## ' + x.h2);
if (x.note) docChunks.push(x.note);
a.forEach(y => docChunks.push(
'### ' + y.title,
'### ' + y.h3,
'```solidity\n' + y.def + '\n```',
y.natspec
));
}
});

if (writeDoc) {
if (docChunks.length) {
writeSync(
getDocPath(srcPath),
[
Expand All @@ -216,23 +213,23 @@ async function main() {
}
});

docSrcPaths.sort();
if (docSrcPaths.length > 0) {
const docDirs = [...new Set(docSrcPaths.map(getSrcDir))];
const sidebarLinks = docDirs.map(dir =>
'- ' + dir + '\n' +
docSrcPaths.filter(p => getSrcDir(p) === dir)
.map(p => ' - [' + getTitle(p) + '](' + getDocSubPath(p) + ')')
.join('\n')
).join('\n');

if (docSrcPaths.length) {
const sidebarDocPath = 'docs' + path.sep + 'sidebar.md';
writeSync(
sidebarDocPath,
replaceInTag(readSync(sidebarDocPath), 'gen', sidebarLinks)
);
replaceInTag(
readSync(sidebarDocPath),
'gen',
[...new Set(docSrcPaths.map(getSrcDir))]
.map(dir => '- ' + dir + '\n' +
docSrcPaths
.filter(p => getSrcDir(p) === dir)
.map(p => ' - [' + getTitle(p) + '](' + getDocSubPath(p) + ')')
.join('\n')
).join('\n')
)
);
}

};

main().catch(e => {
Expand Down

0 comments on commit a5b0222

Please sign in to comment.