Update docs pipeline to solidity-docgen@0.6 (#3707)
Francisco
2 years ago
committed by
GitHub
parent
26dddee1c0
commit
c52625018b
@ -0,0 +1,21 @@ |
||||
const path = require('path'); |
||||
const fs = require('fs'); |
||||
|
||||
/** @type import('solidity-docgen/dist/config').UserConfig */ |
||||
module.exports = { |
||||
outputDir: 'docs/modules/api/pages', |
||||
templates: 'docs/templates', |
||||
exclude: ['mocks'], |
||||
pageExtension: '.adoc', |
||||
pages: (_, file, config) => { |
||||
// For each contract file, find the closest README.adoc and return its location as the output page path.
|
||||
const sourcesDir = path.resolve(config.root, config.sourcesDir); |
||||
let dir = path.resolve(config.root, file.absolutePath); |
||||
while (dir.startsWith(sourcesDir)) { |
||||
dir = path.dirname(dir); |
||||
if (fs.existsSync(path.join(dir, 'README.adoc'))) { |
||||
return path.relative(sourcesDir, dir) + config.pageExtension; |
||||
} |
||||
} |
||||
}, |
||||
}; |
||||
@ -1,91 +0,0 @@ |
||||
{{~#*inline "typed-variable-array"~}} |
||||
{{#each .}}{{typeName}}{{#if name}} {{name}}{{/if}}{{#unless @last}}, {{/unless}}{{/each}} |
||||
{{~/inline~}} |
||||
|
||||
{{#each linkable}} |
||||
:{{name}}: pass:normal[xref:#{{anchor}}[`++{{name}}++`]] |
||||
{{/each}} |
||||
|
||||
[.contract] |
||||
[[{{anchor}}]] |
||||
=== `++{{name}}++` link:{{github-link file.path}}[{github-icon},role=heading-link] |
||||
|
||||
[.hljs-theme-light.nopadding] |
||||
```solidity |
||||
import "@openzeppelin/contracts/{{file.path}}"; |
||||
``` |
||||
|
||||
{{natspec.devdoc}} |
||||
|
||||
{{#if ownModifiers}} |
||||
[.contract-index] |
||||
.Modifiers |
||||
-- |
||||
{{#each ownModifiers}} |
||||
* {xref-{{slug anchor~}} }[`++{{name}}({{args.names}})++`] |
||||
{{/each}} |
||||
-- |
||||
{{/if}} |
||||
|
||||
{{#if functions}} |
||||
[.contract-index] |
||||
.Functions |
||||
-- |
||||
{{#each inheritedItems}} |
||||
{{#if (or @first (ne contract.name "Context"))}} |
||||
{{#unless @first}} |
||||
[.contract-subindex-inherited] |
||||
.{{contract.name}} |
||||
{{/unless}} |
||||
{{#each functions}} |
||||
* {xref-{{slug anchor~}} }[`++{{name}}({{args.names}})++`] |
||||
{{/each}} |
||||
|
||||
{{/if}} |
||||
{{/each}} |
||||
-- |
||||
{{/if}} |
||||
|
||||
{{#if events}} |
||||
[.contract-index] |
||||
.Events |
||||
-- |
||||
{{#each inheritedItems}} |
||||
{{#unless @first}} |
||||
[.contract-subindex-inherited] |
||||
.{{contract.name}} |
||||
{{/unless}} |
||||
{{#each events}} |
||||
* {xref-{{slug anchor~}} }[`++{{name}}({{args.names}})++`] |
||||
{{/each}} |
||||
|
||||
{{/each}} |
||||
-- |
||||
{{/if}} |
||||
|
||||
{{#each ownModifiers}} |
||||
[.contract-item] |
||||
[[{{anchor}}]] |
||||
==== `[.contract-item-name]#++{{name}}++#++({{> typed-variable-array args}})++` [.item-kind]#modifier# |
||||
|
||||
{{natspec.devdoc}} |
||||
|
||||
{{/each}} |
||||
|
||||
{{#each ownFunctions}} |
||||
[.contract-item] |
||||
[[{{anchor}}]] |
||||
==== `[.contract-item-name]#++{{name}}++#++({{> typed-variable-array args}}){{#if outputs}} → {{> typed-variable-array outputs}}{{/if}}++` [.item-kind]#{{visibility}}# |
||||
|
||||
{{natspec.devdoc}} |
||||
|
||||
{{/each}} |
||||
|
||||
{{#each ownEvents}} |
||||
[.contract-item] |
||||
[[{{anchor}}]] |
||||
==== `[.contract-item-name]#++{{name}}++#++({{> typed-variable-array args}})++` [.item-kind]#event# |
||||
|
||||
{{natspec.devdoc}} |
||||
|
||||
{{/each}} |
||||
@ -1,10 +0,0 @@ |
||||
const { version } = require('../package.json'); |
||||
|
||||
module.exports = { |
||||
'github-link': (contractPath) => { |
||||
if (typeof contractPath !== 'string') { |
||||
throw new Error('Missing argument'); |
||||
} |
||||
return `https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v${version}/contracts/${contractPath}`; |
||||
}, |
||||
}; |
||||
@ -1,6 +0,0 @@ |
||||
:github-icon: pass:[<svg class="icon"><use href="#github-icon"/></svg>] |
||||
|
||||
{{#links}} |
||||
:{{slug target.fullName}}: pass:normal[xref:{{path}}#{{target.anchor}}[`{{target.fullName}}`]] |
||||
:xref-{{slug target.anchor}}: xref:{{path}}#{{target.anchor}} |
||||
{{/links}} |
||||
@ -0,0 +1,85 @@ |
||||
{{#each items}} |
||||
:{{name}}: pass:normal[xref:#{{anchor}}[`++{{name}}++`]] |
||||
{{/each}} |
||||
|
||||
[.contract] |
||||
[[{{anchor}}]] |
||||
=== `++{{name}}++` link:https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v{{oz-version}}/{{__item_context.file.absolutePath}}[{github-icon},role=heading-link] |
||||
|
||||
[.hljs-theme-light.nopadding] |
||||
```solidity |
||||
import "@openzeppelin/{{__item_context.file.absolutePath}}"; |
||||
``` |
||||
|
||||
{{{natspec.dev}}} |
||||
|
||||
{{#if modifiers}} |
||||
[.contract-index] |
||||
.Modifiers |
||||
-- |
||||
{{#each modifiers}} |
||||
* {xref-{{anchor~}} }[`++{{name}}({{names params}})++`] |
||||
{{/each}} |
||||
-- |
||||
{{/if}} |
||||
|
||||
{{#if has-functions}} |
||||
[.contract-index] |
||||
.Functions |
||||
-- |
||||
{{#each inherited-functions}} |
||||
{{#unless @first}} |
||||
[.contract-subindex-inherited] |
||||
.{{contract.name}} |
||||
{{/unless}} |
||||
{{#each functions}} |
||||
* {xref-{{anchor~}} }[`++{{name}}({{names params}})++`] |
||||
{{/each}} |
||||
|
||||
{{/each}} |
||||
-- |
||||
{{/if}} |
||||
|
||||
{{#if has-events}} |
||||
[.contract-index] |
||||
.Events |
||||
-- |
||||
{{#each inheritance}} |
||||
{{#unless @first}} |
||||
[.contract-subindex-inherited] |
||||
.{{name}} |
||||
{{/unless}} |
||||
{{#each events}} |
||||
* {xref-{{anchor~}} }[`++{{name}}({{names params}})++`] |
||||
{{/each}} |
||||
|
||||
{{/each}} |
||||
-- |
||||
{{/if}} |
||||
|
||||
{{#each modifiers}} |
||||
[.contract-item] |
||||
[[{{anchor}}]] |
||||
==== `[.contract-item-name]#++{{name}}++#++({{typed-params params}})++` [.item-kind]#modifier# |
||||
|
||||
{{{natspec.dev}}} |
||||
|
||||
{{/each}} |
||||
|
||||
{{#each functions}} |
||||
[.contract-item] |
||||
[[{{anchor}}]] |
||||
==== `[.contract-item-name]#++{{name}}++#++({{typed-params params}}){{#if returns}} → {{typed-params returns}}{{/if}}++` [.item-kind]#{{visibility}}# |
||||
|
||||
{{{natspec.dev}}} |
||||
|
||||
{{/each}} |
||||
|
||||
{{#each events}} |
||||
[.contract-item] |
||||
[[{{anchor}}]] |
||||
==== `[.contract-item-name]#++{{name}}++#++({{typed-params params}})++` [.item-kind]#event# |
||||
|
||||
{{{natspec.dev}}} |
||||
|
||||
{{/each}} |
||||
@ -0,0 +1,46 @@ |
||||
const { version } = require('../../package.json'); |
||||
|
||||
module.exports['oz-version'] = () => version; |
||||
|
||||
module.exports['readme-path'] = (opts) => { |
||||
return 'contracts/' + opts.data.root.id.replace(/\.adoc$/, '') + '/README.adoc'; |
||||
}; |
||||
|
||||
module.exports.names = (params) => params.map(p => p.name).join(', '); |
||||
|
||||
module.exports['typed-params'] = (params) => { |
||||
return params.map(p => `${p.type}${p.name ? ' ' + p.name : ''}`).join(', '); |
||||
}; |
||||
|
||||
const slug = module.exports.slug = (str) => { |
||||
if (str === undefined) { |
||||
throw new Error('Missing argument'); |
||||
} |
||||
return str.replace(/\W/g, '-'); |
||||
}; |
||||
|
||||
const linksCache = new WeakMap(); |
||||
|
||||
function getAllLinks (items) { |
||||
if (linksCache.has(items)) { |
||||
return linksCache.get(items); |
||||
} |
||||
const res = {}; |
||||
linksCache.set(items, res); |
||||
for (const item of items) { |
||||
res[`xref-${item.anchor}`] = `xref:${item.__item_context.page}#${item.anchor}`; |
||||
res[slug(item.fullName)] = `pass:normal[xref:${item.__item_context.page}#${item.anchor}[\`${item.fullName}\`]]`; |
||||
} |
||||
return res; |
||||
} |
||||
|
||||
module.exports['with-prelude'] = (opts) => { |
||||
const links = getAllLinks(opts.data.site.items); |
||||
const contents = opts.fn(); |
||||
const neededLinks = contents |
||||
.match(/\{[-._a-z0-9]+\}/ig) |
||||
.map(m => m.replace(/^\{(.+)\}$/, '$1')) |
||||
.filter(k => k in links); |
||||
const prelude = neededLinks.map(k => `:${k}: ${links[k]}`).join('\n'); |
||||
return prelude + '\n' + contents; |
||||
}; |
||||
@ -0,0 +1,4 @@ |
||||
:github-icon: pass:[<svg class="icon"><use href="#github-icon"/></svg>] |
||||
{{#with-prelude}} |
||||
{{readme (readme-path)}} |
||||
{{/with-prelude}} |
||||
@ -0,0 +1,49 @@ |
||||
const { isNodeType } = require('solidity-ast/utils'); |
||||
const { slug } = require('./helpers'); |
||||
|
||||
module.exports.anchor = function anchor ({ item, contract }) { |
||||
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; |
||||
}; |
||||
|
||||
module.exports.inheritance = function ({ item, build }) { |
||||
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); |
||||
}; |
||||
|
||||
module.exports['has-functions'] = function ({ item }) { |
||||
return item.inheritance.some(c => c.functions.length > 0); |
||||
}; |
||||
|
||||
module.exports['has-events'] = function ({ item }) { |
||||
return item.inheritance.some(c => c.events.length > 0); |
||||
}; |
||||
|
||||
module.exports['inherited-functions'] = function ({ item }) { |
||||
const { inheritance } = item; |
||||
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), |
||||
), |
||||
})); |
||||
}; |
||||
File diff suppressed because it is too large
Load Diff
@ -1,16 +0,0 @@ |
||||
const hre = require('hardhat'); |
||||
|
||||
const { getCompilersDir } = require('hardhat/internal/util/global-dir'); |
||||
const { CompilerDownloader } = require('hardhat/internal/solidity/compiler/downloader'); |
||||
const { Compiler } = require('hardhat/internal/solidity/compiler'); |
||||
|
||||
const [{ version }] = hre.config.solidity.compilers; |
||||
|
||||
async function getSolc () { |
||||
const downloader = new CompilerDownloader(await getCompilersDir(), { forceSolcJs: true }); |
||||
const { compilerPath } = await downloader.getDownloadedCompilerPath(version); |
||||
const compiler = new Compiler(compilerPath); |
||||
return compiler.getSolc(); |
||||
} |
||||
|
||||
module.exports = Object.assign(getSolc(), { __esModule: true }); |
||||
Loading…
Reference in new issue