Change triggers and file naming

.github/workflows/docs.yml

@@ -1,15 +1,14 @@
-name: Docs
+name: Solidity docs
 
 on:
-# TODO: execute on releases?
+  pull_request: # configured later to run steps only if `solidity/contracts/**` were modified
   push:
     branches:
-      - main
-    paths:
-      - "solidity/contracts/**"
-      - ".github/workflows/docs.yml"
-  pull_request:
-  workflow_dispatch:
+      - releases/mainnet/solidity/**
+  release:
+    types:
+      - "published" # maybe configured later to run steps only for `solidity/`releases
+  workflow_dispatch:    
 
 jobs:
   docs-detect-changes:
@@ -62,7 +61,7 @@ jobs:
             -exec sed -i 's_///[[:blank:]]*_///_' {} \;
           sed -i ':a;N;$!ba;s_///\n//\n_///\n_g' ./contracts/bridge/BitcoinTx.sol
 
-      # TODO: Rebove after testing
+      # TODO: Remove after testing
       - name: Export artifacts
         uses: actions/upload-artifact@master
         with:
@@ -82,21 +81,21 @@ jobs:
       - name: Install dependencies
         run: yarn install --frozen-lockfile
 
-      - name: Build Markdown docs # Outputs files to ./solidity/docs
+      - name: Build Markdown docs # Outputs file to ./solidity/generated-docs/index.md
         run: yarn run hardhat docgen
 
-      # TODO: Rebove after testing
+      # TODO: Remove after testing
       - name: Export artifacts
         uses: actions/upload-artifact@master
         with:
           name: md
-          path: ./solidity/docs
+          path: ./solidity/generated-docs
 
       # - name: Get list of files
       #   id: files-list
       #   run: |
       #     mkdir docs_adoc # create output dir
-      #     echo "files=find ./docs -type f" >> $GITHUB_OUTPUT
+      #     echo "files=find ./generate-docs -type f" >> $GITHUB_OUTPUT
 
       # We need Ruby to install Kramdown AsciiDoc
       - name: Setup Ruby
@@ -109,40 +108,36 @@ jobs:
         run: gem install kramdown-asciidoc
 
       - name: Convert Markdown to Asciidoc
-        run: |
-          find ./docs \
-            -name "*.md" \
-            -type f \
-            -exec sh -c \
-            'kramdoc --output="${1%.md}.adoc" "$1"' _ {} \;
+        run: kramdoc --output=tbtc-v2-contracts.adoc index.md
 
       - name: Add Table of Contents
         run: |
-          sed -i '1s/^/:toclevels: 1 \n/' ./docs/index.adoc
-          sed -i '1s/^/:toc: left \n/' ./docs/index.adoc
+          sed -i '1s/^/:toclevels: 1 \n/' ./generated-docs/tbtc-v2-contracts.adoc
+          sed -i '1s/^/:toc: left \n/' ./generated-docs/tbtc-v2-contracts.adoc
 
       # TODO: Remove after testing
       - name: Export artifacts
         uses: actions/upload-artifact@master
         with:
           name: adoc
-          path: ./solidity/docs
+          path: ./solidity/generated-docs
 
       - name: Build HTML docs
         id: html
         uses: thesis/[email protected]
         with:
-          files: './solidity/docs/*.adoc ./solidity/docs/**/*.adoc'
+          files: './solidity/generated-docs/tbtc-v2-contracts.adoc'
           args: '-a revdate=`date +%Y-%m-%d` --failure-level=ERROR'
 
+      # TODO: Remove after testing
       - name: Export artifacts
         uses: actions/upload-artifact@master
         with:
           name: asciidoc-out
           path: ./asciidoc-out
 
-      # # A push event is a main merge; deploy to primary bucket.
-      # - if: github.event_name == 'push'
+      # # Triggered for Solidity releases 
+      # - if: github.event_name == 'release' && startsWith(github.ref, 'refs/tags/solidity/')
       #   name: Upload asciidocs
       #   uses: thesis/[email protected]
       #   with:
@@ -152,8 +147,12 @@ jobs:
       #     bucket-path: .
       #     build-folder: ${{ steps.html.outputs.asciidoctor-artifacts }}/docs
 
+      # TODO: Remove after testing
+      - name: List artifacts
+        run: echo ${{ steps.html.outputs.asciidoctor-artifacts }}
+
       # # A pull_request event is a PR; deploy to preview bucket.
-      # - if: github.event_name == 'pull_request'
+      # - if: github.event_name == 'pull_request' || github.event_name == 'push'
       #   name: Upload asciidocs preview
       #   uses: thesis/[email protected]
       #   with:
@@ -172,5 +171,5 @@ jobs:
       #         issue_number: context.issue.number,
       #         owner: context.repo.owner,
       #         repo: context.repo.repo,
-      #         body: 'Documentation preview uploaded to https://docs.keep.network/${{ github.head_ref }}/index.html.'
+      #         body: 'Documentation preview uploaded to https://docs.keep.network/${{ github.head_ref }}/tbtc-v2-contracts.html.'
       #       })

solidity/hardhat.config.ts

@@ -248,6 +248,7 @@ const config: HardhatUserConfig = {
     outDir: "typechain",
   },
   docgen: {
+    outputDir: "generated-docs",
     templates: "docgen-templates",
     exclude: ['./test'],
   },