diff --git a/.github/workflows/contracts-docs.yml b/.github/workflows/contracts-docs.yml index 5d13a508..e8dd3486 100644 --- a/.github/workflows/contracts-docs.yml +++ b/.github/workflows/contracts-docs.yml @@ -39,7 +39,7 @@ jobs: needs.docs-detect-changes.outputs.path-filter == 'true' || github.event_name == 'push' || github.event_name == 'workflow_dispatch' - uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@main + uses: ./.github/workflows/reusable-solidity-docs.yml with: publish: false addTOC: false @@ -56,7 +56,7 @@ jobs: name: Publish contracts documentation needs: docs-detect-changes if: github.event_name == 'release' && startsWith(github.ref, 'refs/tags/v') - uses: keep-network/ci/.github/workflows/reusable-solidity-docs.yml@main + uses: ./.github/workflows/reusable-solidity-docs.yml with: publish: true addTOC: false diff --git a/.github/workflows/contracts.yml b/.github/workflows/contracts.yml index 3dafdfe8..7670c597 100644 --- a/.github/workflows/contracts.yml +++ b/.github/workflows/contracts.yml @@ -57,13 +57,15 @@ jobs: steps: - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 + - uses: actions/setup-node@v4 with: # Using fixed version, because 18.16 was sometimes causing issues with # artifacts generation during `hardhat compile` - see # https://github.com/NomicFoundation/hardhat/issues/3877 node-version: "18.15.0" - cache: "yarn" + + - name: Enable Corepack (Yarn from packageManager field) + run: corepack enable - name: Install dependencies run: yarn install @@ -80,13 +82,15 @@ jobs: steps: - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 + - uses: actions/setup-node@v4 with: # Using fixed version, because 18.16 was sometimes causing issues with # artifacts generation during `hardhat compile` - see # https://github.com/NomicFoundation/hardhat/issues/3877 node-version: "18.15.0" - cache: "yarn" + + - name: Enable Corepack (Yarn from packageManager field) + run: corepack enable - name: Install dependencies run: yarn install @@ -103,15 +107,17 @@ jobs: steps: - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 + - uses: actions/setup-node@v4 with: # Using fixed version, because 18.16 was sometimes causing issues with # artifacts generation during `hardhat compile` - see # https://github.com/NomicFoundation/hardhat/issues/3877 node-version: "18.15.0" - cache: "yarn" registry-url: "https://registry.npmjs.org" + - name: Enable Corepack (Yarn from packageManager field) + run: corepack enable + - name: Install dependencies run: yarn install --frozen-lockfile @@ -172,13 +178,15 @@ jobs: with: name: Artifacts for etherscan verifcation - - uses: actions/setup-node@v3 + - uses: actions/setup-node@v4 with: # Using fixed version, because 18.16 was sometimes causing issues with # artifacts generation during `hardhat compile` - see # https://github.com/NomicFoundation/hardhat/issues/3877 node-version: "18.15.0" - cache: "yarn" + + - name: Enable Corepack (Yarn from packageManager field) + run: corepack enable - name: Install needed dependencies run: yarn install --frozen-lockfile @@ -204,15 +212,17 @@ jobs: steps: - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 + - uses: actions/setup-node@v4 with: # Using fixed version, because 18.16 was sometimes causing issues with # artifacts generation during `hardhat compile` - see # https://github.com/NomicFoundation/hardhat/issues/3877 node-version: "18.15.0" - cache: "yarn" registry-url: "https://registry.npmjs.org" + - name: Enable Corepack (Yarn from packageManager field) + run: corepack enable + - name: Install dependencies run: yarn install --frozen-lockfile @@ -259,13 +269,15 @@ jobs: steps: - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 + - uses: actions/setup-node@v4 with: # Using fixed version, because 18.16 was sometimes causing issues with # artifacts generation during `hardhat compile` - see # https://github.com/NomicFoundation/hardhat/issues/3877 node-version: "18.15.0" - cache: "yarn" + + - name: Enable Corepack (Yarn from packageManager field) + run: corepack enable - uses: actions/setup-python@v4 with: diff --git a/.github/workflows/format.yml b/.github/workflows/format.yml index 87fd5f55..f47edde6 100644 --- a/.github/workflows/format.yml +++ b/.github/workflows/format.yml @@ -13,10 +13,12 @@ jobs: steps: - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 + - uses: actions/setup-node@v4 with: node-version: "18" - cache: "yarn" + + - name: Enable Corepack (Yarn from packageManager field) + run: corepack enable - name: Install dependencies run: yarn install diff --git a/.github/workflows/npm.yml b/.github/workflows/npm.yml index 5f1857b9..22dbb8fa 100644 --- a/.github/workflows/npm.yml +++ b/.github/workflows/npm.yml @@ -18,14 +18,16 @@ jobs: steps: - uses: actions/checkout@v3 - - uses: actions/setup-node@v3 + - uses: actions/setup-node@v4 with: # Using fixed version, because 18.16 may cause issues with the # artifacts generation during `hardhat compile` - see # https://github.com/NomicFoundation/hardhat/issues/3877. node-version: "18.15.0" registry-url: "https://registry.npmjs.org" - cache: "yarn" + + - name: Enable Corepack (Yarn from packageManager field) + run: corepack enable - name: Install needed dependencies run: yarn install --frozen-lockfile diff --git a/.github/workflows/reusable-solidity-docs.yml b/.github/workflows/reusable-solidity-docs.yml new file mode 100644 index 00000000..eff6e9c7 --- /dev/null +++ b/.github/workflows/reusable-solidity-docs.yml @@ -0,0 +1,298 @@ +name: Generate and push Solidity API documentation + +# Vendored from keep-network/ci (reusable-solidity-docs.yml) with Corepack enabled +# so Yarn 4 from package.json "packageManager" works on GitHub Actions. +# Upstream: https://github.com/keep-network/ci/blob/main/.github/workflows/reusable-solidity-docs.yml + +# To use this workflow, make sure `solidity-docgen` package is added to the +# projects's dev dependencies and is configured in Hardhat config (see +# https://github.com/OpenZeppelin/solidity-docgen#usage). +# The workflow expects `outputDir` to be set to `generated-docs`. You may +# also need to specify other configs, like `templates` or `exclude`. +on: + workflow_call: + inputs: + projectDir: + description: "A root's subfolder containing the `contracts` folder and + the Yarn / Hardhat configuration. Leave empty ('') if the project + config resides in the root. If config resides in a subfolder, provide + the subfolder name/path, without leading `.` and ending `/`. For + example, type `/v2/solidity` if the path to the `contracts` folder is + `./v2/solidity/contracts`." + type: string + required: false + default: "" + trimComments: + description: "True if you want to remove space characters between `///` + and a comment text in the Solidity files, before generating `.md` + files. This may be needed to improve the look of the lists in the + generated files." + type: boolean + required: false + default: true + preProcessingCommand: + description: "An optional additional bash command to be executed before + transforming the Solidity files to Markdown file(s). The command will + be executed in the path specified by `projectDir`." + type: string + required: false + addTOC: + description: "True if you want to add Table Of Contents to the generated + Markdown file. Uses `markdown-toc` tool to generate TOC. Shouldn't be + set to `true` if Docgen's `pages` attribute in `hardhat.config.ts` is + set to `items` or `files`." + type: boolean + required: false + default: true + tocOptions: + description: "Options to be passed to the `markdown-toc` tool used for + generation of Table Of Contents. See + https://github.com/jonschlinkert/markdown-toc#cli for more details." + type: string + required: false + default: "-i --maxdepth 2" + postProcessingCommand: + description: "An optional additional bash command to be executed after + transforming the Solidity files to Markdown file(s). The command will + be executed in the path specified by `projectDir`." + type: string + required: false + publish: + description: "True if you want to push the generated file(s) to the + destination repository." + type: boolean + required: false + default: true + verifyCommits: + description: "True if you want to sign commits updating the docs using + GPG key. You'll need to specify `gpgPrivateKey` and `gpgPassphrase` + secrets." + type: boolean + required: false + default: false + destinationRepo: + description: "A name of the repository where the generated Solidity docs + will be pushed to. Required if `publish=true`." + type: string + required: false + destinationFolder: + description: "A path in the destination repository where the generated + Solidity docs will be pushed to. For example, `./docs-api/tbtc-v2`." + type: string + required: false + default: "." + destinationBaseBranch: + description: "A branch on the destination repository which will be set + as a base branch of the PR updating Solidity docs (must exist)." + type: string + required: false + default: "main" + userEmail: + description: "The email address of a GitHub user associated with the + `githubToken` secret. Will be used to sign commits. Required if + `publish=true`." + type: string + required: false + userName: + description: "The name of the GitHub user associated with the + `githubToken` secret. Will be used to sign commits. Required if + `publish=true`." + type: string + required: false + rsyncDelete: + description: "True if you want to delete from the destination folder + the files which were not generated during current run of the workflow. + Usually there shouldn't be need to set this option to `true` if + Docgen's `pages` attribute in `hardhat.config.ts` is set to `single`. + In other cases the option should be use with caution." + type: boolean + required: false + default: false + commentPR: + description: "True if you want to add a comment with the path to the + generated files in the PR invoking the workflow. If the workflow is + not triggered by the `pull_request` event, having this input set to + `true` will not brake the execution." + type: boolean + required: false + default: false + exportAsGHArtifacts: + description: "True if you want to see the artifacts generated on various + stages of workflow execution in the GH run details." + type: boolean + required: false + default: false + secrets: + githubToken: + description: "A GitHub API token for the destination organization. + Should have `repo` scope. Required if `publish=true`." + required: false + gpgPrivateKey: + description: "A GPG private key needed when `verifyCommits` is set to + true. See + https://github.com/crazy-max/ghaction-import-gpg#prerequisites for + instructions on key generation." + required: false + gpgPassphrase: + description: "A passphrase of the GPG key. Needed when `verifyCommits` + is set to true." + required: false + +jobs: + docs-generate-html-and-publish: + runs-on: ubuntu-latest + defaults: + run: + working-directory: .${{ inputs.projectDir }} + steps: + - uses: actions/checkout@v3 + + # In this step we modify the format of the comments in the Solidity + # contracts files. We do that because our original formatting is not + # processed by Docgen in the way we would like. + # To nicely display lists (like the list of requirements) we need to + # remove multiple space chars after the `///` comment. We do that by + # executing `sed 's_///[[:blank:]]*_///_'` on all contracts files, which + # substitutes `///` + 0 or more spaces/tabs with just `///`. + + - name: Prepare contract files for further processing + if: inputs.trimComments + shell: bash + run: | + find ./contracts \ + -name "*.sol" \ + -type f \ + -exec sed -i 's_///[[:blank:]]*_///_' {} \; + + - name: Execute additional command + if: inputs.preProcessingCommand != null + shell: bash + run: ${{ inputs.preProcessingCommand }} + + - name: Export artifacts + if: inputs.exportAsGHArtifacts == true + uses: actions/upload-artifact@master + with: + name: contracts-after-preprocessing + path: .${{ inputs.projectDir }}/contracts + + # We may need this step in case we execute the workflow in a project + # that has a dependency to `@summa-tx/relay-sol@2.0.2` package, which + # downloads one of its sub-dependencies via unathenticated `git://` + # protocol. That protocol is no longer supported. Thanks to this step + # `https://` is used instead of `git://`. + - name: Configure git to don't use unauthenticated protocol + shell: bash + run: git config --global url."https://".insteadOf git:// + + - uses: actions/setup-node@v4 + with: + # Using fixed version, because 18.16 was sometimes causing issues with + # artifacts generation during `hardhat compile` - see + # https://github.com/NomicFoundation/hardhat/issues/3877 + node-version: "18.15.0" + + - name: Enable Corepack (Yarn from packageManager field) + run: corepack enable + + - name: Install dependencies + shell: bash + run: yarn install --frozen-lockfile + + # Generates `.md` file(s) based on config in the `hardhat.config.ts`. + - name: Build Markdown docs + run: yarn run hardhat docgen + + - name: Add Table of Contents + if: inputs.addTOC == true + run: | + yarn global add markdown-toc + sed -i '2s/^/\