We are creating GH Actions workflows which automatically generates the contracts
documentation in Markdown, based on the functions and the NatSpec-format
comments in the Solidity files stored in the `contracts` folders in
`keep-network/keep-core/solidity/random-beacon` and
`keep-network/keep-core/solidity/ecdsa`. For certain workflow triggers, the
generated documentation will be pushed to the `threshold-network/threshold`
repository, under `./docs/app-development/random-beacon/random-beacon-api` /
`./docs/app-development/ecdsa/ecdsa-api`. As the `.docs` folder is synched with
Threshold docs GitBook space, the pushed docs will be displayed in HTML under
`docs.threshold.network` domain.

There are two main jobs in the workflows:

* `contracts-docs-publish-preview`
* `contracts-docs-publish`

Both call a reusable workflow `reusable-solidity-docs.yml` which resides in the
`keep-network/ci` repository under `.github/workflows`. The jobs differ in
parameters with witch the reusable action is called. The common part of the jobs
is the beginning stage, where the Solidity files are being prepared for Markdown
generation. During that stage the jobs will remove the spaces chars between the
NatSpec comments markers (`///`) and the text of the comment. This is done to
ensure proper rendering of the lists in the output docs and is a default
action made by `reusable-solidity-docs.yml`. Another pre-processing is
running a `sed` command on a `./contracts/bridge/BitcoinTx.sol` that removes
incorrectly used line with `//` blank comment in the middle of section with
NatSpec's `///` comments (which was breaking the formatting of that comment in
Markdown).
Once files are ready, the jobs use Docgen tool to generate the Markdown docs.
The tool needs to be installed in the project and configured in the
`hardhat.config.ts`. The configuration that we use specifies that the docs
should be generated to the `geerated-docs` subfolder, to one single `index.md`
file. The `.sol` files in the `./solidity/contracts/test` folder will be
ignored during generation (those are test/stub contracts which are not used on
Mainnet). A custom template will be used during docs generations. The template
was created based on the default
`https://github.com/OpenZeppelin/solidity-docgen/blob/master/src/themes/markdown/common.hbs`
template, but it removes the cursive from the `@dev` type comments (because the
cursive didn't work well with formatting of the lists).
Once the Docgen is run and the `index.md` file is generated, the jobs will add
a Table of Contents to the file, to improve the navigation. The TOC will be
added by the `markdown-toc` tool and will be generated using `--maxdepth 2`
param, which results in listing all the contract names, but not the functions.
Once the TOC is added, we'll start to see the difference in the behavior of the
jobs.

The `contracts-docs-publish-preview` job is triggered for:
* `pull_request` events, if the PR modifies either files if
  `./solidity/<project>/contracts` or the workflow files itself,
* `push` events, when the push is made to a branch which name starts with
  `releases/mainnet/solidity/` and project's files are modified,
* `workflow_dispatch` events.
The job publishes the generated artifacts as artifacts of the GH Actions
workflow run. For PRs, link to the run with the artifacts will be posted as a PR
comment.

The `contracts-docs-publish` job is triggered for:
* published releases, which names start with `refs/tags/solidity/`.
The job pushes the generated file to the
`./docs/app-development/random-beacon/random-beacon-api` /
`./docs/app-development/ecdsa/ecdsa-api`folder in the
`threshold-network/threshold` repo, to the `main` branch. The `.docs` folder
is synched with the GitBook Threshold documentation, so thanks to the job, the
changes in the contracts should be reflected on the docs.threshold.network.
In order for the job to work, we need to configure a user which will create the
commit The user needs to have right to commit to the
`threshold-network/threshold` repo. We also need to configure following secrets:
- [ ] `THRESHOLD_DOCS_GITHUB_TOKEN`
- [ ] `GPG_PRIVATE_KEY`
- [ ] `GPG_PASSPHRASE`
We're using a GPG key to be able to do verified commits.

The name of the input in the reusable action has changed, we're updating the
name in the jobs that use it.

We decided to push the docs updates not directly to branch synched with GitBook,
but create a PR and set a GitBook-synched branch as a base branch for that PR.
This resulted in changes in the
`keep-network/ci/.github/workflows/reusable-solidity-docs.yml`
workflow's inputs.

Change introduced to fix the 'Your push would publish a private email address.'
error.

…tbook

…tbook

The workflow is meant to publish the docs on new releases, but as we already
had releases when workflow wasn't implemented, we need to publish the docs
representing the current state of the API. We are satisfied with docummenting
based on the `main` branch state. After docs get publish, we need to revert this
change.

As triggers for the `Publish contracts documentation` jobs in the workflows
generating Random Beacon and ECDSA API docs are the same (and also the
previously executed steps are very similar, it's likely that the both jobs will
start and the same or very similar time.
When that happens it's very likely that the both jobs will pull the
`auto-update-solidity-api-docs` branch at the same state and one of the jobs
will push a commit with updated docs, while the other won't be able to do that,
as the state of the branch will be different than when the pull happened.
The error we see in that case is following:
```
error: failed to push some refs to 'https://github.com/threshold-network/threshold.git'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.
```
To avoid such situations we add a 4 minutes wait before we execute the 'Publish
contracts documentation' job in ECDSA workflow. This should be more than
enught for the Random Beacon's `Publish contracts documentation` to finish.

There is still a small change that both `Publish contracts documentation` jobs
will run at similar time (if something slows down the execution of the Random
Beacon workflow) and cause a failure of one of them, but in that unlikely
scenario, we can always rerun the failing job and it should pass on that second
run.