Feature Request: md documentation generation from natspec

[simluyt]

Component

Forge

Describe the feature you would like

A nice feature that is included in most dev tools is the generation of documentation using natspec. In the past there have been a multitude of tools that do this. OpenZeppelin has solidity-docgen to generate markdown form natspec solidity code and afaik this is also what hardhat-docgen is using.

Ideally there would be a new subcommand for forge like

forge docgen

that generates documentation from natspec to markdown (or other formats) that can be used to populate a gitbook, docs.rs, docusaurus or any other style documentation website.

Example:
forge docgen --md
could generate markdown from natspec like this:

 /**
   * @dev Withdraws an `amount` of underlying asset from the reserve, burning the equivalent aTokens owned
   * E.g. User has 100 aUSDC, calls withdraw() and receives 100 USDC, burning the 100 aUSDC
   * @param asset The address of the underlying asset to withdraw
   * @param amount The underlying amount to be withdrawn
   *   - Send the value type(uint256).max in order to withdraw the whole aToken balance
   * @param to Address that will receive the underlying, same as msg.sender if the user
   *   wants to receive it on his own wallet, or a different address if the beneficiary is a
   *   different wallet
   * @return The final amount withdrawn
   **/
  function withdraw(
    address asset,
    uint256 amount,
    address to
  ) external returns (uint256);

to this:

### withdraw

'''solidity
  function withdraw(
    address asset,
    uint256 amount,
    address to
  ) external returns (uint256);'''


@notice here if there was one

*@dev here: Withdraws an `amount` of underlying asset from the reserve, burning the equivalent aTokens owned
   * E.g. User has 100 aUSDC, calls withdraw() and receives 100 USDC, burning the 100 aUSDC**

#### Parameters

| Name | Type | Description |
|---|---|---|
| asset | address | The address of the underlying asset to withdraw. |
| amount | uint256 | The underlying amount to be withdrawn. |
| to | address | Address that will receive the underlying... |

#### Returns

| Name | Type | Description |
|---|---|---|
| undefined | uint256 | The final amount withdrawn |

which could be used in the documentation services mentioned before.

hardhat docgen gives additional options like --output, --exclude and a bunch of others which might also be useful here.

Additional context

No response

[onbjerg]

There are some things I would like for a Forge documentation generator:

• Structured file names and paths, like docs.rs. For example, docs for:
  • Contracts would be something like relative/path/contract.SomeContract.html
  • Structs would be struct.SomeStruct.html
  • And so on
• Support for rustdoc-style docs. Natspec is kind of annoying (imo), so it would be nice to have some sort of Rustdoc-like comment format where the first sentence is userdoc and the next sentences (after an empty line) would be devdoc or something similar
• Docs for contracts, libraries, events and interfaces
• "Module-level" docs like we have in Rust for mod.rs so you can create index pages
• Output to HTML and Markdown
• Easy linking to other parts of the code, like in Rust, where you can do e.g. [SomeStruct] and it would link to the struct if it is in scope, or [SomeInterface] and so on

This would allow us to build a docs.rs for Solidity

[mattsse]

Ref gakonst/ethers-rs#1182

[onbjerg]

I'm going to close this issue in favor of #1675