Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/sambacha/solidity-handlebars
solidity interface and natspec handlebar templates
https://github.com/sambacha/solidity-handlebars
ethereum generate handlebars natspec solidity template
Last synced: about 1 month ago
JSON representation
solidity interface and natspec handlebar templates
- Host: GitHub
- URL: https://github.com/sambacha/solidity-handlebars
- Owner: sambacha
- Created: 2021-02-09T05:45:01.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2022-05-13T23:05:25.000Z (over 2 years ago)
- Last Synced: 2024-12-13T01:45:42.736Z (about 1 month ago)
- Topics: ethereum, generate, handlebars, natspec, solidity, template
- Language: Handlebars
- Homepage:
- Size: 32.2 KB
- Stars: 2
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# `solidity-handlebars`
> Handlebar Templates for generating solidity contract interfaces and documentation
## Usage
### Create `.natspec.yaml` file
```yaml
root: ./
structure:
readme: ./docs/README.md
summary: ./docs/SUMMARY.md
```
- Install [email protected] (version)
- run node src/index.js
- ?????
## Solidity DocGen
> [natspec source](https://github.com/snreynolds/solidity-docgen/commit/154b7acf80f120127e4640db6f8a052d96d6c6cc) via @snreynolds
**Documentation generator for smart contract libraries.** Use the inline
documentation in your Solidity code for generating websites or any sort of
document.
The output is completely customizable through Handlebars templates that provide
easy access to all the metadata of your smart contract.
## Solidity DocGen Documentation
```sh
npm install solidity-docgen
```
`solidity-docgen` takes as input a directory of contracts and `README`
documents. This directory is specified using the `--input`/`-i` flag,
defaulting to `./contracts`. It produces a set of files that it will place in
the output directory specified by `--output`/`-o`, defaulting to `./docs`.
```
solidity-docgen [ -i ] [ -o ] [ -t ]
```
[natspec]: https://solidity.readthedocs.io/en/develop/natspec-format.html
### Solidity 0.7
The built in compiler remains solc 0.6, but users who want to use the newer compiler version can do so by installing the desired solc version and using the flag `--solc-module`. Here's an example using npm aliases:
```
npm install -D solc-0.7@npm:solc@^0.7.0
npx solidity-docgen --solc-module solc-0.7
```
## Example Handlebars Formatting
Each of the following examples will go through various methods exposed by the solidity-docgen library, how to use them in handlebars, and what the resulting markdown output would look like.
1. Getting the natspec @dev and @notice tags
### Handlebars formatting:
```{{{natspec.userdoc}}}
{{{natspec.devdoc}}}
```
### Markdown output:
This is the comment next to the @notice tag.
This is the comment next to the @dev tag.
2. Functions and Events
Your handlebars template can check if the underlying contract code is a function or an event with {{#if ownFunctions}} and {{#if ownEvents}} respectively. This lets you generate different markdown depending on if the underlying natspec is for functions or events. Use {{ownFunctions}} and {{ownEvents}} to iterate over all functions and events in the contract respectively.
### Handlebars formatting:
```{{#if ownFunctions}
### Functions
{{/if}}
{{#ownFunctions}}
- function {{name}}
{{/ownFunctions}}
{{/if ownFunctions}}
```
### Markdown Output:
### Functions
- function example1
- function example2
- function example3
3. Getting more data about a funcion
In 2. we saw how to iterate over the functions in a contract and each of the function names. Here is an example that gets more information related to a function including the input parameters, and visibility.
### Handlebars formatting:
```{{#if ownFunctions}
### Functions
{{/if}}
{{#ownFunctions}}
#### function {{name}}
Parameters:
{{natspec.params}}
- {{param}}
{{/natspec.params}}
Visibility:
- {{visibility}}
{{#if outputs}}
Outputs:
- {{outputs}}
{{/if}}
{{/ownFunctions}}
{{/if ownFunctions}}
```
### Markdown Output:
### Functions
#### function example1
Parameters:
- param1
- param2
Visibliity:
- external
Outputs:
- bool return1
#### function example2
Parameters:
- param1
- param2
- param3
Visibliity:
- internal
Outputs:
- uint128 return0, uint128 return1
#### function example3
Parameters:
- param1
Visibliity:
- external
Outputs:
- int24 return1
4. Formatting a function signature
The nice thing about handlebars templating is that it just populates data into a markdown format. So you can use any markdown syntax to arrange your data such that it looks pretty when the markdown is generated! (The below does some fancy handlebar manipulation that you don't really need to understand. It essentially is populating the types of the parameters so that the output in markdown looks like a function signature.)
### Handlebars formatting:
````
### {{name}}
```solidity
function {{name}}(
{{#natspec.params}}
{{#lookup ../args.types @index}}{{/lookup}} {{param}}{{#if @last}}{{else}},{{/if}}
{{/natspec.params}}
) {{visibility}}{{#if outputs}} returns ({{outputs}}){{/if}}```
````
### Markdown Output:
Here is what the output for the example1 function would look like.
### example1
```solidity
function example1(
int24 param1,
int24 param2
) external returns (bool return1)
```