Skip to content

docgen: support hardhat3-style branches in injectTemplates #174

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ernestognw wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docgen: support hardhat3-style branches in injectTemplates #174

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions docgen/config-md.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
import path from 'path';
import fs from 'fs';

/** @type import('solidity-docgen/dist/config').UserConfig */
export default {
outputDir: 'docs/modules/api/pages',
templates: 'docs/templates',
exclude: ['mocks'],
pageExtension: '.mdx',
pages: (_, file, config) => {
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;
}
}
},
};
30 changes: 15 additions & 15 deletions docgen/templates-md/contract.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
{{reset-function-counts}}<a id="{{anchor}}"></a>
{{resetFunctionCounts}}<a id="{{anchor}}"></a>

<div style=\{{marginTop: "4em"}} className="w-full flex flex-row items-center justify-between">

## `{{{name}}}`

<a target="_blank" style=\{{marginTop: "1.5em"}} href="https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v{{oz-version}}/{{__item_context.file.absolutePath}}">
<a target="_blank" style=\{{marginTop: "1.5em"}} href="https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v{{ozVersion}}/{{__item_context.file.absolutePath}}">
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-github-icon lucide-github"><path d="M15 22v-4a4.8 4.8 0 0 0-1-3.5c3 0 6-2 6-5.5.08-1.25-.27-2.48-1-3.5.28-1.15.28-2.35 0-3.5 0 0-1 0-3 1.5-2.64-.5-5.36-.5-8 0C6 2 5 2 5 2c-.3 1.15-.3 2.35 0 3.5A5.403 5.403 0 0 0 4 9c0 3.5 3 5.5 6 5.5-.39.49-.68 1.05-.85 1.65-.17.6-.22 1.23-.15 1.85v4"/><path d="M9 18c-4.51 2-5-2-7-2"/></svg>
</a>

Expand All @@ -14,7 +14,7 @@
import "@openzeppelin/{{__item_context.file.absolutePath}}";
```

{{{process-natspec natspec.dev}}}
{{{processNatspec natspec.dev}}}

{{#if modifiers}}
<div className="bg-secondary p-4 rounded-md mb-6">
Expand All @@ -28,11 +28,11 @@ import "@openzeppelin/{{__item_context.file.absolutePath}}";
{{/if}}


{{#if has-functions}}
{{#if hasFunctions}}
<div className="bg-secondary p-4 rounded-md mb-6">
<h3 style=\{{ marginTop: "0"}}>Functions</h3>
<div className="font-mono">
{{#each inherited-functions}}
{{#each inheritedFunctions}}
{{#if @first}}
{{#each functions}}
- [{{{name}}}({{names params}})](#{{anchor}})
Expand All @@ -54,7 +54,7 @@ import "@openzeppelin/{{__item_context.file.absolutePath}}";
</div>
{{/if}}

{{#if has-events}}
{{#if hasEvents}}
<div className="bg-secondary p-4 rounded-md mb-6">
<h3 style=\{{ marginTop: "0"}}>Events</h3>
<div className="font-mono">
Expand All @@ -80,7 +80,7 @@ import "@openzeppelin/{{__item_context.file.absolutePath}}";
</div>
{{/if}}

{{#if has-errors}}
{{#if hasErrors}}
<div className="bg-secondary p-4 rounded-md mb-6">
<h3 style=\{{ marginTop: "0"}}>Errors</h3>
<div className="font-mono">
Expand Down Expand Up @@ -111,7 +111,7 @@ import "@openzeppelin/{{__item_context.file.absolutePath}}";

<div className="border rounded-md mb-4">
<div className="bg-secondary flex w-full justify-between px-4">
<p className="font-bold text-sm font-mono">{{{name}}}({{typed-params params}})</p>
<p className="font-bold text-sm font-mono">{{{name}}}({{typedParams params}})</p>
<div className="flex flex-row items-center gap-2">
<p className="font-light text-sm">{{visibility}}</p>
<a className="peer" data-card href="#{{anchor}}">#</a>
Expand All @@ -120,7 +120,7 @@ import "@openzeppelin/{{__item_context.file.absolutePath}}";

<div className="px-4">

{{{process-natspec natspec.dev}}}
{{{processNatspec natspec.dev}}}

</div>
</div>
Expand All @@ -132,15 +132,15 @@ import "@openzeppelin/{{__item_context.file.absolutePath}}";

<div className="border rounded-md mb-4">
<div className="bg-secondary flex w-full justify-between px-4">
<p className="font-bold text-sm font-mono">{{{name}}}({{typed-params params}}){{#if returns2}} → {{typed-params returns2}}{{/if}}</p>
<p className="font-bold text-sm font-mono">{{{name}}}({{typedParams params}}){{#if returns2}} → {{typedParams returns2}}{{/if}}</p>
<div className="flex flex-row items-center gap-2">
<p className="font-light text-sm">{{visibility}}</p>
<a className="peer" data-card href="#{{anchor}}">#</a>
</div>
</div>
<div className="px-4">

{{{process-natspec natspec.dev}}}
{{{processNatspec natspec.dev}}}

</div>
</div>
Expand All @@ -152,7 +152,7 @@ import "@openzeppelin/{{__item_context.file.absolutePath}}";

<div className="border rounded-md mb-4">
<div className="bg-secondary flex w-full justify-between px-4">
<p className="font-bold text-sm font-mono">{{{name}}}({{typed-params params}})</p>
<p className="font-bold text-sm font-mono">{{{name}}}({{typedParams params}})</p>
<div className="flex flex-row items-center gap-2">
<p className="font-light text-sm">event</p>
<a className="peer" data-card href="#{{anchor}}">#</a>
Expand All @@ -161,7 +161,7 @@ import "@openzeppelin/{{__item_context.file.absolutePath}}";

<div className="px-4">

{{{process-natspec natspec.dev}}}
{{{processNatspec natspec.dev}}}

</div>
</div>
Expand All @@ -172,15 +172,15 @@ import "@openzeppelin/{{__item_context.file.absolutePath}}";

<div className="border rounded-md mb-4">
<div className="bg-secondary flex w-full justify-between px-4">
<p className="font-bold text-sm font-mono">{{{name}}}({{typed-params params}})</p>
<p className="font-bold text-sm font-mono">{{{name}}}({{typedParams params}})</p>
<div className="flex flex-row items-center gap-2">
<p className="font-light text-sm">error</p>
<a className="peer" data-card href="#{{anchor}}">#</a>
</div>
</div>
<div className="px-4">

{{{process-natspec natspec.dev}}}
{{{processNatspec natspec.dev}}}

</div>
</div>
Expand Down
18 changes: 9 additions & 9 deletions docgen/templates-md/helpers.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ const os = require('os');

const API_DOCS_PATH = 'contracts/5.x/api';

module.exports['oz-version'] = () => version;
module.exports.ozVersion = () => version;

module.exports['readme-path'] = opts => {
module.exports.readmePath = opts => {
const pageId = opts.data.root.id;
const basePath = pageId.replace(/\.(adoc|mdx)$/, '');
return 'contracts/' + basePath + '/README.adoc';
Expand All @@ -31,7 +31,7 @@ module.exports.names = params => params?.map(p => p.name).join(', ');
// Simple function counter for unique IDs
const functionNameCounts = {};

module.exports['simple-id'] = function (name) {
module.exports.simpleId = function (name) {
if (!functionNameCounts[name]) {
functionNameCounts[name] = 1;
return name;
Expand All @@ -41,7 +41,7 @@ module.exports['simple-id'] = function (name) {
}
};

module.exports['reset-function-counts'] = function () {
module.exports.resetFunctionCounts = function () {
Object.keys(functionNameCounts).forEach(key => delete functionNameCounts[key]);
return '';
};
Expand All @@ -52,13 +52,13 @@ module.exports.eq = (a, b) => a === b;
// import specifier for non-`contracts` packages, where the file is published
// at the package root (e.g. @openzeppelin/community-contracts/account/X.sol)
// but the source lives at contracts/account/X.sol in the repo.
module.exports['strip-contracts-prefix'] = function (p) {
module.exports.stripContractsPrefix = function (p) {
return typeof p === 'string' ? p.replace(/^contracts\//, '') : p;
};
module.exports['starts-with'] = (str, prefix) => str && str.startsWith(prefix);
module.exports.startsWith = (str, prefix) => str && str.startsWith(prefix);

// Process natspec content with {REF} and link replacement
module.exports['process-natspec'] = function (natspec, opts) {
module.exports.processNatspec = function (natspec, opts) {
if (!natspec) return '';

const currentPage = opts.data.root.__item_context?.page || opts.data.root.id;
Expand All @@ -68,7 +68,7 @@ module.exports['process-natspec'] = function (natspec, opts) {
return processCallouts(processed); // Add callout processing at the end
};

module.exports['typed-params'] = params => {
module.exports.typedParams = params => {
return params?.map(p => `${p.type}${p.indexed ? ' indexed' : ''}${p.name ? ' ' + p.name : ''}`).join(', ');
};

Expand Down Expand Up @@ -497,7 +497,7 @@ module.exports.description = opts => {
return `Smart contract ${dirName.replace('-', ' ')} utilities and implementations`;
};

module.exports['with-prelude'] = opts => {
module.exports.withPrelude = opts => {
const currentPage = opts.data.root.id;
const links = getAllLinks(opts.data.site.items, currentPage);
const contents = opts.fn();
Expand Down
6 changes: 3 additions & 3 deletions docgen/templates-md/page.hbs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@ title: "{{title}}"
description: "{{description}}"
---

{{#with-prelude}}
{{readme (readme-path)}}
{{/with-prelude}}
{{#withPrelude}}
{{readme (readmePath)}}
{{/withPrelude}}

{{#each items}}
{{>contract}}
Expand Down
14 changes: 7 additions & 7 deletions docgen/templates-md/properties.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,24 +44,24 @@ module.exports.inheritance = function ({ item, build }) {
.filter((c, i) => c.name !== 'Context' || i === 0);
};

module.exports['has-functions'] = function ({ item }) {
module.exports.hasFunctions = function ({ item }) {
return item.inheritance && item.inheritance.some(c => c.functions.length > 0);
};

module.exports['has-events'] = function ({ item }) {
module.exports.hasEvents = function ({ item }) {
return item.inheritance && item.inheritance.some(c => c.events.length > 0);
};

module.exports['has-errors'] = function ({ item }) {
module.exports.hasErrors = function ({ item }) {
return item.inheritance && item.inheritance.some(c => c.errors.length > 0);
};

module.exports['internal-variables'] = function ({ item }) {
module.exports.internalVariables = function ({ item }) {
return item.variables ? item.variables.filter(({ visibility }) => visibility === 'internal') : [];
};

module.exports['has-internal-variables'] = function ({ item }) {
return module.exports['internal-variables']({ item }).length > 0;
module.exports.hasInternalVariables = function ({ item }) {
return module.exports.internalVariables({ item }).length > 0;
};

module.exports.functions = function ({ item }) {
Expand All @@ -79,7 +79,7 @@ module.exports.returns2 = function ({ item }) {
}
};

module.exports['inherited-functions'] = function ({ item }) {
module.exports.inheritedFunctions = function ({ item }) {
const { inheritance } = item;
if (!inheritance) return [];

Expand Down
Loading