docs: segregate api docs url/deployment (#3602)

Author: nedsalk

.changeset/khaki-hairs-heal.md

@@ -0,0 +1,4 @@
+---
+---
+
+docs: segregate api docs url/deployment

.github/workflows/release.yaml

@@ -125,17 +125,29 @@ jobs:
           HOME: ${{ github.workspace }}
           npm_config_registry: "https://npm.pkg.github.com"
 
-      # ensure docs are always deployed after merge of changeset PR
+      # ensure docs API is always deployed after merge of changeset PR
       - name: Get the last commit message and set env vars
         run: echo LAST_COMMIT_MSG=$(git --no-pager log -1 --pretty=%B) >> $GITHUB_ENV
 
-      - name: Decides if Docs should be deployed
+      - name: Decides if Docs API should be deployed
         if: startsWith(env.LAST_COMMIT_MSG, 'ci(release):') && env.RELEASE_VERSION_HIGHER_THAN_LATEST == 'true'
-        run: echo SHOULD_DEPLOY_DOCS=true >> $GITHUB_ENV
+        run: echo DEPLOY_STABLE_DOCS_API=true >> $GITHUB_ENV
+
+      # nightly docs API gets updated on every merge to master
+      # and is configured in the vercel dashboard
+      # stable docs API gets updated only when a new release is published
+      - name: Update Docs API (stable)
+        if: github.ref_name == 'master' && env.DEPLOY_STABLE_DOCS_API == 'true'
+        env:
+          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_TS_DOCS_API_PROJECT_ID }}
+        run: |
+          pnpm install --global vercel@latest
+          vercel --prod --token=${{ secrets.VERCEL_TOKEN }}
 
       # # Commenting out as we require permissions to trigger across repos
-      # - name: Update docs (nightly)
-      #   if: github.ref_name == 'master' && env.SHOULD_DEPLOY_DOCS == 'true'
+      # - name: Update docs
+      #   if: github.ref_name == 'master'
       #   uses: benc-uk/workflow-dispatch@v1
       #   with:
       #     workflow: update-nightly.yml

apps/docs-api/index.md

@@ -12,15 +12,15 @@
 
 # Modules
 
-- [abi-coder](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_abi_coder.html)
-- [abi-typegen](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_abi_typegen.html)
-- [account](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_account.html)
-- [address](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_address.html)
-- [crypto](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_crypto.html)
-- [errors](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_errors.html)
-- [hasher](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_hasher.html)
-- [math](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_math.html)
-- [program](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_program.html)
-- [script](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_script.html)
-- [transactions](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_transactions.html)
-- [utils](https://fuels-ts-docs-api.vercel.app/modules/_fuel_ts_utils.html)
+- [abi-coder](modules/_fuel_ts_abi_coder.html)
+- [abi-typegen](modules/_fuel_ts_abi_typegen.html)
+- [account](modules/_fuel_ts_account.html)
+- [address](modules/_fuel_ts_address.html)
+- [crypto](modules/_fuel_ts_crypto.html)
+- [errors](modules/_fuel_ts_errors.html)
+- [hasher](modules/_fuel_ts_hasher.html)
+- [math](modules/_fuel_ts_math.html)
+- [program](modules/_fuel_ts_program.html)
+- [script](modules/_fuel_ts_script.html)
+- [transactions](modules/_fuel_ts_transactions.html)
+- [utils](modules/_fuel_ts_utils.html)

apps/docs/.vitepress/config.ts

@@ -14,8 +14,21 @@ export default defineConfig({
       md.use(snippetPlugin);
       md.use(codeInContextPlugin);
       md.block.ruler.disable('snippet');
+      md.core.ruler.before('normalize', 'replace-docs-api-url', (state) => {
+        const apiUrl = process.env.NODE_ENV === 'development' ? 'http://localhost:5174' : '/api';
+        state.src = state.src.replace(/DOCS_API_URL/g, apiUrl);
+      });
     },
   },
+  transformHtml: (code) => {
+    // make the API links open in a new tab
+    // because opening in the same tab doesn't work in the preview
+    return code.replace(/(<a\s+[^>]*href="\/api\/[^"]*")/g, '$1 target="_blank" rel="noreferrer"');
+  },
+  // Finds dead DOCS_API_URL links and fails,
+  // but they get replaced later in the markdown transformer.
+  // We have the md link checker workflow which covers this.
+  ignoreDeadLinks: true,
   head: [
     ['link', { rel: 'icon', href: '/fuels-ts/favicon.ico', type: 'image/png' }],
     ['meta', { property: 'og:type', content: 'website' }],

apps/docs/package.json

@@ -5,14 +5,18 @@
   "description": "",
   "type": "module",
   "scripts": {
-    "dev": "nodemon --config nodemon.config.json -x 'run-s build:snippets dev:docs'",
+    "dev": "nodemon --config nodemon.config.json -x 'run-s build:snippets build:docs-api dev:docs'",
     "build": "run-s build:snippets build:docs",
-    "preview": "run-s build:snippets preview:docs",
+    "preview": "run-s build:snippets build:docs-api preview:docs",
     "test": "cd ../.. && pnpm run test:filter apps/docs",
     "build:snippets": "run-s wrap:snippets build:forc",
-    "build:docs": "vitepress build",
+    "build:docs": "run-s build:docs-app build:docs-api",
+    "build:docs-app": "vitepress build",
+    "build:docs-api": "cd ../docs-api && pnpm build && cp -r ./src/api ../docs/dist",
     "preview:docs": "vitepress preview",
-    "dev:docs": "vitepress dev",
+    "preview:docs-api": "pnpm vite preview --port 5174 --outDir ../docs-api/src/api",
+    "dev:docs": "run-p docs:dev preview:docs-api",
+    "docs:dev": "vitepress dev",
     "wrap:snippets": "tsx ./scripts/wrap-snippets.ts",
     "build:forc": "pnpm fuels build --deploy",
     "type:check": "pnpm tsc --noEmit --project tsconfig.emit.json"

apps/docs/src/guide/contracts/contract-balance.md

@@ -1,10 +1,10 @@
 # Contract Balance
 
-When working with contracts, it's crucial to be aware of the available contract balance of an asset while paying for costly operations. This guide will explain the `getBalance` method in the [Contract](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_program.Contract.html) class, which allows you to check a contract's available balance.
+When working with contracts, it's crucial to be aware of the available contract balance of an asset while paying for costly operations. This guide will explain the `getBalance` method in the [Contract](DOCS_API_URL/classes/_fuel_ts_program.Contract.html) class, which allows you to check a contract's available balance.
 
 ## The `getBalance` Method
 
-The [`Contract.getBalance`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_program.Contract.html#getBalance) method retrieves the available balance of a specific asset on your contract. This method is particularly useful for determining the remaining balance after sending assets to a contract and executing contract calls.
+The [`Contract.getBalance`](DOCS_API_URL/classes/_fuel_ts_program.Contract.html#getBalance) method retrieves the available balance of a specific asset on your contract. This method is particularly useful for determining the remaining balance after sending assets to a contract and executing contract calls.
 
 It is important to note that this method returns the total available contract balance, regardless of how often assets have been sent to it or spent.
 

apps/docs/src/guide/contracts/cost-estimation.md

@@ -1,6 +1,6 @@
 # Estimating Contract Call Cost
 
-The [`FunctionInvocationScope.getTransactionCost`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_program.FunctionInvocationScope.html#getTransactionCost) method allows you to estimate the cost of a specific contract call. The return type, `TransactionCost`, is an object containing relevant information for the estimation:
+The [`FunctionInvocationScope.getTransactionCost`](DOCS_API_URL/classes/_fuel_ts_program.FunctionInvocationScope.html#getTransactionCost) method allows you to estimate the cost of a specific contract call. The return type, `TransactionCost`, is an object containing relevant information for the estimation:
 
 <<< @/../../../packages/account/src/providers/provider.ts#cost-estimation-1{ts:line-numbers}
 

apps/docs/src/guide/contracts/dependency-estimation.md

@@ -4,6 +4,6 @@ In [variable outputs](./variable-outputs.md), we mention that a contract call mi
 
 However, by default the SDK always automatically estimates these dependencies and double-checks if everything is in order whenever you invoke a contract function or attempt to send a transaction.
 
-The SDK uses the [Provider.estimateTxDependencies](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_account.Provider.html#estimateTxDependencies) method to set any missing dependencies identified during the estimation process. This requires simulating the transaction a few times in the background.
+The SDK uses the [Provider.estimateTxDependencies](DOCS_API_URL/classes/_fuel_ts_account.Provider.html#estimateTxDependencies) method to set any missing dependencies identified during the estimation process. This requires simulating the transaction a few times in the background.
 
 While relying on the SDK's automatic estimation is a decent default behavior, we recommend manually specifying the dependencies if they are known in advance to avoid the performance impact of the estimation process.

apps/docs/src/guide/contracts/deploying-contracts.md

@@ -53,7 +53,7 @@ Now that the contract is deployed, you can interact with it by submitting a cont
 
 ## Deploying a Large Contract as Blobs
 
-In the above guide we use the recommended `deploy` method. If you are working with a contract that is too large to be deployed in a single transaction, then the SDK will chunk the contract for you and submit it as blobs, to then be accessed later by a create transaction. This process is handled by the [`ContractFactory.deployAsBlobTx`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_contract.index.ContractFactory.html#deployAsBlobTx) method.
+In the above guide we use the recommended `deploy` method. If you are working with a contract that is too large to be deployed in a single transaction, then the SDK will chunk the contract for you and submit it as blobs, to then be accessed later by a create transaction. This process is handled by the [`ContractFactory.deployAsBlobTx`](DOCS_API_URL/classes/_fuel_ts_contract.index.ContractFactory.html#deployAsBlobTx) method.
 
 <<< @./snippets/deploying-contracts/deployment.ts#blobs{ts:line-numbers}
 

apps/docs/src/guide/contracts/managing-deployed-contracts.md

@@ -4,9 +4,9 @@ To interact with a deployed contract using the SDK without redeploying it, you o
 
 ## Contract ID
 
-The `contractId` property from the [`Contract`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_program.Contract.html) class is an instance of the [`Address`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_address.Address.html) class.
+The `contractId` property from the [`Contract`](DOCS_API_URL/classes/_fuel_ts_program.Contract.html) class is an instance of the [`Address`](DOCS_API_URL/classes/_fuel_ts_address.Address.html) class.
 
-The [`Address`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_address.Address.html) class also provides a set of utility functions for easy manipulation and conversion between address formats along with one property; `b256Address`, which is a string encoded in [`B256`](../types/b256.md) format.
+The [`Address`](DOCS_API_URL/classes/_fuel_ts_address.Address.html) class also provides a set of utility functions for easy manipulation and conversion between address formats along with one property; `b256Address`, which is a string encoded in [`B256`](../types/b256.md) format.
 
 When you log the `contractId` property of an instantiated Contract using `console.log`, the output appears as follows:
 
@@ -22,10 +22,10 @@ If you have already an instantiated and deployed contract in hands you can creat
 
 <<< @./snippets/managing-deployed-contracts.ts#with-contractId{ts:line-numbers}
 
-The previous example assumes that you have a [`Contract`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_program.Contract.html) instance at hand. However, some Fuel tools and Sway use the [`B256`](../types/b256.md) type format, a hex-encoded string-like type, for contract IDs.
+The previous example assumes that you have a [`Contract`](DOCS_API_URL/classes/_fuel_ts_program.Contract.html) instance at hand. However, some Fuel tools and Sway use the [`B256`](../types/b256.md) type format, a hex-encoded string-like type, for contract IDs.
 
 You might have this format instead, for example, if you have deployed your contract with `forc deploy`.
 
-The process of instantiating a [`Contract`](https://fuels-ts-docs-api.vercel.app/classes/_fuel_ts_program.Contract.html) remains the same when using a contract ID of type `B256`:
+The process of instantiating a [`Contract`](DOCS_API_URL/classes/_fuel_ts_program.Contract.html) remains the same when using a contract ID of type `B256`:
 
 <<< @./snippets/managing-deployed-contracts.ts#with-b256{ts:line-numbers}