Skip to content

Commit e19328f

Browse files
stevedylandevstevedylandev
committed
chore: added docgen templates and instructions
1 parent 42829e2 commit e19328f

File tree

7 files changed

+770
-3
lines changed

7 files changed

+770
-3
lines changed

‎README.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -131,6 +131,52 @@ Product-specific icons located in `src/components/icons/`:
131131
- **Version Switching**: Multi-version documentation support
132132
- **Responsive Design**: Mobile-optimized navigation and content
133133

134+
## Solidity Docgen
135+
136+
Any library using Solidity Docgen can utilize the `docgen` templates and config file in their repo to generate markdown API references for the docs. To get started follow the instructions below:
137+
138+
### 1. Add the templates to your repo
139+
140+
Inside this docs repo is the `docgen` folder which contains `templates-md` and `config-md.js`. Copy both of these items into your `docs` folder in your repo. Once there open the `templates-md/helpers.js` file and update the `API_DOCS_PATH` constant to match your export path.
141+
142+
```js
143+
const API_DOCS_PATH = 'contracts/5.x/api';
144+
// const API_DOCS_PATH = 'community-contracts/api';
145+
// const API_DOCS_PATH = 'confidential-contracts/api';
146+
// const API_DOCS_PATH = 'uniswap-hooks/api';
147+
```
148+
149+
### 2. Update the `hardhat.config.js` file
150+
151+
With the `config-md.js` file now in the `docs` folder, update your `hardhat.config.js` to use the new config file.
152+
153+
```js
154+
{
155+
// other config options
156+
docgen: require('./docs/config-md'),
157+
}
158+
```
159+
160+
Once added make sure these are accessible in your branches going forward. If you are generating an API reference for previous branches you will need to repeat steps 1 and 2 for those branches.
161+
162+
### 3. Run the `generate-api-docs.js` script
163+
164+
With your remote repo setup with the new template files you can run the `scripts/generate-api-docs.js` script. Be sure to pass in the correct arguements for your docs
165+
166+
```bash
167+
node scripts/generate-api-docs.js \
168+
--repo https://github.com/OpenZeppelin/openzeppelin-community-contracts.git \
169+
--branch release-v5.5 \
170+
--api-output content/contracts/5.x/api \
171+
--examples-output examples
172+
```
173+
174+
This wil lexport the contents to
175+
176+
### Automated Setup
177+
178+
In the case you want to setup an automated GitHub workflow to create these API docs visit the [docs-api-generation-workflows](https://github.com/OpenZeppelin/docs-api-generation-workflows) for more info. This repo (`OpenZeppelin/docs`) is the `Docs Receiver` side of the equation.
179+
134180
## Content Management
135181

136182
### Adding New Content

‎docgen/config-md.js‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
const path = require('path');
2+
const fs = require('fs');
3+
4+
/** @type import('solidity-docgen/dist/config').UserConfig */
5+
module.exports = {
6+
outputDir: 'docs/modules/api/pages',
7+
templates: 'docs/templates-md',
8+
exclude: ['mocks'],
9+
pageExtension: '.mdx',
10+
pages: (_, file, config) => {
11+
const sourcesDir = path.resolve(config.root, config.sourcesDir);
12+
let dir = path.resolve(config.root, file.absolutePath);
13+
while (dir.startsWith(sourcesDir)) {
14+
dir = path.dirname(dir);
15+
if (fs.existsSync(path.join(dir, 'README.adoc'))) {
16+
return path.relative(sourcesDir, dir) + config.pageExtension;
17+
}
18+
}
19+
},
20+
};

‎docgen/templates-md/contract.hbs‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
{{reset-function-counts}}<a id="{{anchor}}"></a>
2+
3+
<div style=\{{marginTop: "4em"}} className="w-full flex flex-row items-center justify-between">
4+
5+
## `{{{name}}}`
6+
7+
<a target="_blank" style=\{{marginTop: "1.5em"}} href="https://github.com/OpenZeppelin/openzeppelin-contracts/blob/v{{oz-version}}/{{__item_context.file.absolutePath}}">
8+
<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>
9+
</a>
10+
11+
</div>
12+
13+
```solidity
14+
import "@openzeppelin/{{__item_context.file.absolutePath}}";
15+
```
16+
17+
{{{process-natspec natspec.dev}}}
18+
19+
{{#if modifiers}}
20+
<div className="bg-secondary p-4 rounded-md mb-6">
21+
<h3 style=\{{ marginTop: "0"}}>Modifiers</h3>
22+
<div className="font-mono">
23+
{{#each modifiers}}
24+
- [{{{name}}}({{names params}})](#{{anchor}})
25+
{{/each}}
26+
</div>
27+
</div>
28+
{{/if}}
29+
30+
31+
{{#if has-functions}}
32+
<div className="bg-secondary p-4 rounded-md mb-6">
33+
<h3 style=\{{ marginTop: "0"}}>Functions</h3>
34+
<div className="font-mono">
35+
{{#each inherited-functions}}
36+
{{#unless @first}}
37+
#### {{contract.name}} [!toc]
38+
{{/unless}}
39+
{{#each functions}}
40+
- [{{{name}}}({{names params}})](#{{anchor}})
41+
{{/each}}
42+
{{/each}}
43+
</div>
44+
</div>
45+
{{/if}}
46+
47+
{{#if has-events}}
48+
<div className="bg-secondary p-4 rounded-md mb-6">
49+
<h3 style=\{{ marginTop: "0"}}>Events</h3>
50+
<div className="font-mono">
51+
{{#each inheritance}}
52+
{{#unless @first}}
53+
#### {{name}} [!toc]
54+
{{/unless}}
55+
{{#each events}}
56+
- [{{{name}}}({{names params}})](#{{anchor}})
57+
{{/each}}
58+
{{/each}}
59+
</div>
60+
</div>
61+
{{/if}}
62+
63+
{{#if has-errors}}
64+
<div className="bg-secondary p-4 rounded-md mb-6">
65+
<h3 style=\{{ marginTop: "0"}}>Errors</h3>
66+
<div className="font-mono">
67+
{{#each inheritance}}
68+
{{#unless @first}}
69+
#### {{name}} [!toc]
70+
{{/unless}}
71+
{{#each errors}}
72+
- [{{{name}}}({{names params}})](#{{anchor}})
73+
{{/each}}
74+
{{/each}}
75+
</div>
76+
</div>
77+
{{/if}}
78+
79+
{{#each modifiers}}
80+
<a id="{{anchor}}"></a>
81+
82+
<div className="border rounded-md mb-4">
83+
<div className="bg-secondary flex w-full justify-between px-4">
84+
<p className="font-bold text-sm font-mono">{{{name}}}({{typed-params params}})</p>
85+
<div className="flex flex-row items-center gap-2">
86+
<p className="font-light text-sm">{{visibility}}</p>
87+
<a className="peer" data-card href="{{anchor}}">#</a>
88+
</div>
89+
</div>
90+
91+
<div className="px-4">
92+
93+
{{{process-natspec natspec.dev}}}
94+
95+
</div>
96+
</div>
97+
98+
{{/each}}
99+
100+
{{#each functions}}
101+
<a id="{{anchor}}"></a>
102+
103+
<div className="border rounded-md mb-4">
104+
<div className="bg-secondary flex w-full justify-between px-4">
105+
<p className="font-bold text-sm font-mono">{{{name}}}({{typed-params params}}){{#if returns2}} → {{typed-params returns2}}{{/if}}</p>
106+
<div className="flex flex-row items-center gap-2">
107+
<p className="font-light text-sm">{{visibility}}</p>
108+
<a className="peer" data-card href="{{anchor}}">#</a>
109+
</div>
110+
</div>
111+
<div className="px-4">
112+
113+
{{{process-natspec natspec.dev}}}
114+
115+
</div>
116+
</div>
117+
118+
{{/each}}
119+
120+
{{#each events}}
121+
<a id="{{anchor}}"></a>
122+
123+
<div className="border rounded-md mb-4">
124+
<div className="bg-secondary flex w-full justify-between px-4">
125+
<p className="font-bold text-sm font-mono">{{{name}}}({{typed-params params}})</p>
126+
<div className="flex flex-row items-center gap-2">
127+
<p className="font-light text-sm">event</p>
128+
<a className="peer" data-card href="{{anchor}}">#</a>
129+
</div>
130+
</div>
131+
132+
<div className="px-4">
133+
134+
{{{process-natspec natspec.dev}}}
135+
136+
</div>
137+
</div>
138+
{{/each}}
139+
140+
{{#each errors}}
141+
<a id="{{anchor}}"></a>
142+
143+
<div className="border rounded-md mb-4">
144+
<div className="bg-secondary flex w-full justify-between px-4">
145+
<p className="font-bold text-sm font-mono">{{{name}}}({{typed-params params}})</p>
146+
<div className="flex flex-row items-center gap-2">
147+
<p className="font-light text-sm">error</p>
148+
<a className="peer" data-card href="{{anchor}}">#</a>
149+
</div>
150+
</div>
151+
<div className="px-4">
152+
153+
{{{process-natspec natspec.dev}}}
154+
155+
</div>
156+
</div>
157+
158+
{{/each}}

0 commit comments

Comments
 (0)