[Feat] Automate smart contract docgen and PR branch creation into Lin…

…ea docs repo (#446)

* did poc for autogenerated *.mdx into docs.linea.build

* changed sparseMerkleProof

* first draft of contracts-docgen

* fix typos

* try different github token

* cleanup

* created create-docs-website-pr-branch

* cleanup for doc website repo scripts

* created first docs-repo pr using create-docs-website-pr-branch.sh

* improve comments

* added bash script segment to change filename to lowercase

* fix *.mdx headers to make more docusarus friendly

* update scripts for updated docs pr

* added comments to updateSidebar.js

* fix scripts after local test

* added installation checks

* Update contracts/docs/scripts/create-docs-website-pr-branch.sh

Co-authored-by: The Dark Jester <[email protected]>
Signed-off-by: kyzooghost <[email protected]>

---------

Signed-off-by: kyzooghost <[email protected]>
Co-authored-by: The Dark Jester <[email protected]>

.github/workflows/codeql.yml

@@ -18,6 +18,9 @@ on:
       # '!**.md' will not work by itself to exclude *.md files. See https://github.com/orgs/community/discussions/25369
       - '**'
       - '!**.md'
+      - '!**.mdx'
+      - '!**/docs/**'
+      - '!docs/**'
 
 jobs:
   analyze:

.github/workflows/main.yml

@@ -122,6 +122,8 @@ jobs:
           filters: |
             has-changes-requiring-build:
               - '!**/*.md'
+              - '!**/*.mdx'
+              - '!**/docs/**'
               - '!docs/**'
           # Enables us to exclude changes in multiple file types if required
           predicate-quantifier: 'every'

.github/workflows/run-smc-tests.yml

@@ -7,8 +7,10 @@ on:
       - 'testdata/**'
       - 'prover/**'
       - '!contracts/**/*.md'
+      - '!contracts/**/*.mdx'
       - '!testdata/**/*.md'
       - '!prover/**/*.md'
+      - '!**/docs/**'
   push:
     branches:
       - main
@@ -17,8 +19,10 @@ on:
       - 'testdata/**'
       - 'prover/**'
       - '!contracts/**/*.md'
+      - '!contracts/**/*.mdx'
       - '!testdata/**/*.md'
       - '!prover/**/*.md'
+      - '!**/docs/**'
 
 env:
   GOPROXY: "https://proxy.golang.org"

contracts/contracts/lib/SparseMerkleProof.sol

@@ -79,7 +79,7 @@ library SparseMerkleProof {
   /**
    * @notice Hash a value using MIMC hash
    * @param _input Value to hash
-   * @return {bytes32} Mimc hash
+   * @return bytes32 Mimc hash
    */
   function mimcHash(bytes calldata _input) external pure returns (bytes32) {
     return Mimc.hash(_input);
@@ -106,7 +106,7 @@ library SparseMerkleProof {
   /**
    * @notice Hash account value
    * @param _value Encoded account value bytes (nonce, balance, storageRoot, mimcCodeHash, keccakCodeHash, codeSize)
-   * @return {bytes32} Account value hash
+   * @return bytes32 Account value hash
    */
   function hashAccountValue(bytes calldata _value) external pure returns (bytes32) {
     Account memory account = _parseAccount(_value);
@@ -128,7 +128,7 @@ library SparseMerkleProof {
   /**
    * @notice Hash storage value
    * @param _value Encoded storage value bytes
-   * @return {bytes32} Storage value hash
+   * @return bytes32 Storage value hash
    */
   function hashStorageValue(bytes32 _value) external pure returns (bytes32) {
     (bytes32 msb, bytes32 lsb) = _splitBytes32(_value);

contracts/docs/api/LineaRollup.md → contracts/docs/api/LineaRollup.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## LineaRollup
+# `LineaRollup`
 
 ### CONTRACT_VERSION
 

contracts/docs/api/ZkEvmV2.md → contracts/docs/api/ZkEvmV2.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## ZkEvmV2
+# `ZkEvmV2`
 
 ### MODULO_R
 

contracts/docs/api/interfaces/IGenericErrors.md → contracts/docs/api/interfaces/IGenericErrors.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## IGenericErrors
+# `IGenericErrors`
 
 ### ZeroAddressNotAllowed
 

contracts/docs/api/interfaces/IMessageService.md → contracts/docs/api/interfaces/IMessageService.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## IMessageService
+# `IMessageService`
 
 ### MessageSent
 

contracts/docs/api/interfaces/IPauseManager.md → contracts/docs/api/interfaces/IPauseManager.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## IPauseManager
+# `IPauseManager`
 
 ### PauseTypeRole
 

contracts/docs/api/interfaces/IPermissionsManager.md → contracts/docs/api/interfaces/IPermissionsManager.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## IPermissionsManager
+# `IPermissionsManager`
 
 ### RoleAddress
 

contracts/docs/api/interfaces/IRateLimiter.md → contracts/docs/api/interfaces/IRateLimiter.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## IRateLimiter
+# `IRateLimiter`
 
 ### RateLimitInitialized
 

contracts/docs/api/interfaces/l1/IL1MessageManager.md → contracts/docs/api/interfaces/l1/IL1MessageManager.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## IL1MessageManager
+# `IL1MessageManager`
 
 ### RollingHashUpdated
 

contracts/docs/api/interfaces/l1/IL1MessageManagerV1.md → contracts/docs/api/interfaces/l1/IL1MessageManagerV1.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## IL1MessageManagerV1
+# `IL1MessageManagerV1`
 
 ### MessageDoesNotExistOrHasAlreadyBeenClaimed
 

contracts/docs/api/interfaces/l1/IL1MessageService.md → contracts/docs/api/interfaces/l1/IL1MessageService.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## IL1MessageService
+# `IL1MessageService`
 
 ### ClaimMessageWithProofParams
 

contracts/docs/api/interfaces/l1/ILineaRollup.md → contracts/docs/api/interfaces/l1/ILineaRollup.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## ILineaRollup
+# `ILineaRollup`
 
 ### InitializationData
 

contracts/docs/api/interfaces/l1/IPlonkVerifier.md → contracts/docs/api/interfaces/l1/IPlonkVerifier.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## IPlonkVerifier
+# `IPlonkVerifier`
 
 ### Verify
 

contracts/docs/api/interfaces/l1/IZkEvmV2.md → contracts/docs/api/interfaces/l1/IZkEvmV2.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## IZkEvmV2
+# `IZkEvmV2`
 
 ### StartingRootHashDoesNotMatch
 

contracts/docs/api/interfaces/l2/IL2MessageManager.md → contracts/docs/api/interfaces/l2/IL2MessageManager.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## IL2MessageManager
+# `IL2MessageManager`
 
 ### RollingHashUpdated
 

contracts/docs/api/interfaces/l2/IL2MessageManagerV1.md → contracts/docs/api/interfaces/l2/IL2MessageManagerV1.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## IL2MessageManagerV1
+# `IL2MessageManagerV1`
 
 ### MinimumFeeChanged
 

contracts/docs/api/interfaces/l2/IL2MessageServiceV1.md → contracts/docs/api/interfaces/l2/IL2MessageServiceV1.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## IL2MessageServiceV1
+# `IL2MessageServiceV1`
 
 ### setMinimumFee
 

contracts/docs/api/lib/CallForwardingProxy.mdx

@@ -0,0 +1,24 @@
+# `CallForwardingProxy`
+
+### target
+
+```solidity
+address target
+```
+
+The underlying target address that is called.
+
+### constructor
+
+```solidity
+constructor(address _target) public
+```
+
+### fallback
+
+```solidity
+fallback() external payable
+```
+
+Defaults to, and forwards all calls to the target address.
+

contracts/docs/api/lib/L2MessageServicePauseManager.md → contracts/docs/api/lib/L2MessageServicePauseManager.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## L2MessageServicePauseManager
+# `L2MessageServicePauseManager`
 
 ### PAUSE_L1_L2_ROLE
 

contracts/docs/api/lib/LineaRollupPauseManager.md → contracts/docs/api/lib/LineaRollupPauseManager.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## LineaRollupPauseManager
+# `LineaRollupPauseManager`
 
 ### PAUSE_L1_L2_ROLE
 

contracts/docs/api/lib/Mimc.md → contracts/docs/api/lib/Mimc.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## Mimc
+# `Mimc`
 
 ### DataMissing
 

contracts/docs/api/lib/PauseManager.md → contracts/docs/api/lib/PauseManager.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## PauseManager
+# `PauseManager`
 
 ### PAUSE_ALL_ROLE
 

contracts/docs/api/lib/PermissionsManager.md → contracts/docs/api/lib/PermissionsManager.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## PermissionsManager
+# `PermissionsManager`
 
 ### __Permissions_init
 

contracts/docs/api/lib/SparseMerkleProof.md → contracts/docs/api/lib/SparseMerkleProof.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## SparseMerkleProof
+# `SparseMerkleProof`
 
 ### Account
 
@@ -130,7 +128,7 @@ Hash a value using MIMC hash
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| [0] | bytes32 | {bytes32} Mimc hash |
+| [0] | bytes32 | bytes32 Mimc hash |
 
 ### getLeaf
 
@@ -190,7 +188,7 @@ Hash account value
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| [0] | bytes32 | {bytes32} Account value hash |
+| [0] | bytes32 | bytes32 Account value hash |
 
 ### hashStorageValue
 
@@ -210,5 +208,5 @@ Hash storage value
 
 | Name | Type | Description |
 | ---- | ---- | ----------- |
-| [0] | bytes32 | {bytes32} Storage value hash |
+| [0] | bytes32 | bytes32 Storage value hash |
 

contracts/docs/api/lib/TokenBridgePauseManager.md → contracts/docs/api/lib/TokenBridgePauseManager.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## TokenBridgePauseManager
+# `TokenBridgePauseManager`
 
 ### PAUSE_INITIATE_TOKEN_BRIDGING_ROLE
 

contracts/docs/api/lib/Utils.md → contracts/docs/api/lib/Utils.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## Utils
+# `Utils`
 
 ### _efficientKeccak
 

contracts/docs/api/messageService/MessageServiceBase.md → contracts/docs/api/messageService/MessageServiceBase.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## MessageServiceBase
+# `MessageServiceBase`
 
 ### messageService
 

contracts/docs/api/messageService/l1/L1MessageManager.md → contracts/docs/api/messageService/l1/L1MessageManager.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## L1MessageManager
+# `L1MessageManager`
 
 ### rollingHashes
 

contracts/docs/api/messageService/l1/L1MessageService.md → contracts/docs/api/messageService/l1/L1MessageService.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## L1MessageService
+# `L1MessageService`
 
 ### systemMigrationBlock
 

contracts/docs/api/messageService/l1/TransientStorageReentrancyGuardUpgradeable.md → contracts/docs/api/messageService/l1/TransientStorageReentrancyGuardUpgradeable.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## TransientStorageReentrancyGuardUpgradeable
+# `TransientStorageReentrancyGuardUpgradeable`
 
 ### ReentrantCall
 

contracts/docs/api/messageService/l1/v1/L1MessageManagerV1.md → contracts/docs/api/messageService/l1/v1/L1MessageManagerV1.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## L1MessageManagerV1
+# `L1MessageManagerV1`
 
 ### INBOX_STATUS_UNKNOWN
 

contracts/docs/api/messageService/l1/v1/L1MessageServiceV1.md → contracts/docs/api/messageService/l1/v1/L1MessageServiceV1.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## L1MessageServiceV1
+# `L1MessageServiceV1`
 
 ### nextMessageNumber
 

contracts/docs/api/messageService/l2/L2MessageManager.md → contracts/docs/api/messageService/l2/L2MessageManager.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## L2MessageManager
+# `L2MessageManager`
 
 ### L1_L2_MESSAGE_SETTER_ROLE
 

contracts/docs/api/messageService/l2/L2MessageService.md → contracts/docs/api/messageService/l2/L2MessageService.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## L2MessageService
+# `L2MessageService`
 
 ### CONTRACT_VERSION
 

contracts/docs/api/messageService/l2/v1/L2MessageManagerV1.md → contracts/docs/api/messageService/l2/v1/L2MessageManagerV1.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## L2MessageManagerV1
+# `L2MessageManagerV1`
 
 ### INBOX_STATUS_UNKNOWN
 

contracts/docs/api/messageService/l2/v1/L2MessageServiceV1.md → contracts/docs/api/messageService/l2/v1/L2MessageServiceV1.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## L2MessageServiceV1
+# `L2MessageServiceV1`
 
 ### MINIMUM_FEE_SETTER_ROLE
 

contracts/docs/api/messageService/lib/MessageHashing.md → contracts/docs/api/messageService/lib/MessageHashing.mdx

@@ -1,6 +1,4 @@
-# Solidity API
-
-## MessageHashing
+# `MessageHashing`
 
 ### _hashMessage