Automatic generation of task scope markdown

[SebastienGllmt]

Describe the feature

Currently if you create a plugin with multiple tasks each in the same scope, you end up duplicating the definition of all your tasks in your code and in your docs. It would be easier if the documentation was automatically generated

I wrote code to do this for my own project that I'm sharing below

task('genDocs', `Generate documentation for tasks of a given scope`)
  .addParam('scope', 'The scope to generate documentation for')
  .setAction(async ({ scope }, hre) => {
    const scopeContent = hre.scopes[scope];
    console.log(scopeContent);

    console.log(`# ${scopeContent.description ?? scope}`);
    console.log(
      `These are all the [hardhat tasks](https://hardhat.org/hardhat-runner/docs/advanced/create-task) available for the scope \`${scope}\`.`
    );
    console.log();
    console.log(`You can call each of these tasks using \`npx hardhat ${scope} task_name\``);
    for (const [name, definition] of Object.entries(scopeContent.tasks)) {
      console.log();
      console.log(`## \`${name}\``);
      console.log(definition.description ?? 'No description provided');
      const parameters = Object.values(definition.paramDefinitions);
      if (parameters.length > 0) {
        console.log();
        console.log('Parameters:');
        for (const param of parameters) {
          let annotations = [];
          if (param.isOptional) {
            annotations.push(`optional`);
            if (param.defaultValue != null) {
              annotations.push(`${param.defaultValue}`);
            }
          }
          if (param.type) {
            annotations.push(`${param.type.name}`);
          }
          const annotationText = annotations.length > 0 ? ` *(${annotations.join(', ')})* ` : '';
          console.log(
            `- **${param.name}**${annotationText}: ${
              param.description ?? 'No description provided'
            }`
          );
        }
      }
    }
  });

Example generation output

# Paima Engine tasks
These are all the [hardhat tasks](https://hardhat.org/hardhat-runner/docs/advanced/create-task) available for the scope `paima`.

You can call each of these tasks using `npx hardhat paima task_name`

## `PaimaL2Contract:submitGameInput`
Submit data to the Paima L2 contract

Parameters:
- **contract** *(optional, string)* : The contracts's address
- **data** *(optional, string)* : The data to submit either hex-encoded (0x...) or Paima concise-encoded

Search terms

generate docs, generate documentation, codegen

[fvictorio]

Hi @SebastienGllmt, thanks for sharing this and sorry for not responding before.

Can you expand a bit on what you are doing here? I'm mainly interested in what you mean by "you end up duplicating the definition of all your tasks in your code and in your docs".

Can you give us an example of, say, a scope with two tasks, what you'd to do with them, and how would you do that manually? That would help us understand if there's something we can have in Hardhat that helps with that use case.

[SebastienGllmt]

For example, you can see the definition of our hardhat tasks here: https://github.com/PaimaStudios/paima-engine/blob/master/packages/contracts/evm-contracts/src/paimaL2.ts#L5

You can see the task definitions already contain a name, description, all the arguments (along with if they're optional, etc.).

Now if you look at our docs for our Hardhat tasks here: https://docs.paimastudios.com/home/libraries/evm-contracts/hardhat-tasks

You can see it contains the same name, description, arguments and everything because I generated the docs using the script I posted above. Had I not written this script, I would have had to manually copy-paste the prose into our docs so people can see the tasks available and what they do

In fact, Hardhat does this kind of document generation in a sense since as you know the entire reason Hardhat provides a way for tasks to provide descriptions of themselves in the code is to document it in the hardhat CLI

[fvictorio]

Ahhh, got it. But just to clarify, this is about tasks in general, right? The fact that they are scoped tasks is not relevant. That's the part that confused me :sweat_smile:

I think this is a great idea for a plugin, but it's probably not something we'd want to add to the core of Hardhat, since the details of how the markdown would look like can be very project-dependent. What do you think?

[schaable]

Closing due to lack of response. However, I am happy to reopen this if more information can be provided.