Add reusable workflow for creation of Solidity API docs

[michalinacienciala]

In this commit we create a reusable workflow which automatically generates the Markdown contracts documentation based on the functions and the NatSpec-format comments in the Solidity files of the specified project. Depending on the value of the workflow's inputs, the workflow may sync the generated files with the specified directory in the external repository (we will use this to push the documentation to a directory that's synchronized with GitBook).

How Markdown documentation gets created and pushed

1. The documentation gets created based on the content of the Solidity files in contracts folder of the specified project (projectSubfolder). Before we run the Docgen tool generating Markdown files, we may need to perform some slight changes to the input files, as some of the formatting we use in the .sol files of the projects where we want to use the action is interpreted by Docgen not the way we would like or is not completely in line with the NatSpec format:
   • In many @dev clauses in the Solidity files we have the lists of requirements or other items which are constructed like this:

      /// @dev Requirements:
      /// - Item one. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
      ///   Nulla sed porttitor enim, sit amet venenatis enim. Donec tincidunt
      ///   auctor velit non eleifend. Nunc sit amet est non ligula condimentum
      ///   mattis.
      /// - Item two. Quisque purus massa, pellentesque in viverra tempus,
      ///   aliquet nec urna.

 This doesn't get recognized by Docgen as a list and is translated to
 regular text, which is displayed as one continuous line. But when the space
 characters between `///` and the text get removed from he `.sol` files, the
 lists are recognized correctly (without breaking interpretation of other
 features). That's why (unless `removeTrailingSpacesInComments` is set to
 `false`) we run `sed -i 's_///[[:blank:]]*_///_' command on all Solidity
 files.

• There may be other problems with the formatting of the input files that may
  need correction. To handle that we allow for specifying
  preProcessingCommand, which can modify the input files according to need.
  An example of such command:
  sed -i ':a;N;$!ba;s_///\n//\n_///\n_g' ./contracts/bridge/BitcoinTx.sol.

2. Once the files are ready, we install dependencies. It is assumed that the
   project in which action will be run has the solidity-docgen package added
   to the list of dev dependencies in package.json.
3. After project is installed we run the Docgen tool. In order for the tool to
   work, the Hardhat config needs to be updated (see
   https://github.com/OpenZeppelin/solidity-docgen#usage for more details). The
   workflow expects outputDir to be set to generated-docs. You may also need
   to specify other configs, like pages, templates or exclude, according
   to the needs of particular project.
   The tool will generate to generated-docs either one index.md file (if
   pages is set to single) or a set of files (if pages is set to items
   or files), with names reflecting their content.
4. If docs are generated to one file, it may be useful to add a Table Of Contents
   to that file, to ease the navigation. This will be done if addTOC is set
   to true. We use markdown-toc tool for TOC generation. The specific
   options that should be used during generation can be specified in the
   tocOptions input.
5. Then (if exportAsGHArtifacts is set to true) we export the generated
   file(s) as GH Actions artifacts. They will be available for download in the
   details of the workflow run.
6. If artifacts were exported, workflow was triggered by a PR and the
   commentPR was set to true, a comment with information where the artifacts
   can be found will be posted in the PR.
7. If publish input was set, we then proceed to the steps pushing the
   generated file(s) to a repository/path/branch specified in the workflow's
   inputs. To do that we first need to make sure we use correct config to be
   able to publish to the destination repository. We need to provide email and
   a username of the user who will be author of the commit. If repository allows
   only for commits from verified users, the verifyCommits input should be
   set to true and the user have the GPG key configured (see
   https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key).
   The GPG private key and a passphrase to the key should be stored as GH
   secrets in the repositories where the workflow will be used. The name of the
   secrets should be passed to the workflow as git_user_signingkey and
   git_commit_gpgsign.
   Apart from configuring aforementioned commiter-related params, a GH secret
   storing GitHub API token (personal access token) for the destination
   repository needs to be provided in the githubToken secret.
   If everything is configured, the workflow syncs the content of the folder
   storing generated docs with the content of the destination directory (using
   rsync). If rsyncDelete input is set to true, the files which exist in the
   destination repository, but don't exist in the generated-docs folder will
   be removed from the destination repo. One may want to set this option if
   Docgen's pages attribute is set to pages or items (so that when a
   contract or its function gets removed, we would remove the corresponding doc
   from the destination repo). The setting should be used with caution!

Refs:
keep-network/tbtc-v2#584
keep-network/keep-core#3534
threshold-network/solidity-contracts#138

[nkuba]

Impressive work! 💯

[nkuba]

Suggested change

	# also need to specify other configs, like `temlates` or `exclude`.
	# also need to specify other configs, like `templates` or `exclude`.