4x clean docs (#6582)

* typedoc config

* libs and scripts update

* libs update

* menus system updates

* doc libs update

* doc place holders so these not filtered

* fix ts error for doc

* config

* sample docs

* removed static doc

* link fix check

* updated conf

* git ignore update

* typedoc tags for grouping and cleaning

* custom typedoc generator

* updated scripts

* comments

* corrected module

* reverted

* unnecessary change

* removed readme as landing page

* fixed docusarus and markdown processing comp issue

* yarn lock of docs

docs/.gitignore

@@ -22,3 +22,5 @@ yarn-error.log*
 
 # Don't include auto generated docs of current version
 docs/api
+
+docs/libdocs

docs/docs/libdocs/.nojekyll

@@ -0,0 +1 @@
+TypeDoc added this file to prevent GitHub Pages from using Jekyll. You can turn off this behavior by setting the `githubPages` option to false.

docs/docusaurus.config.js

@@ -117,6 +117,12 @@ const config = {
 					{
 						to: '/',
 						activeBasePath: '/',
+						label: 'Guides & Tutorials',
+						position: 'left',
+					},
+					{
+						to: '/libdocs/Accounts',
+						activeBasePath: '/libdocs/',
 						label: 'Documentation',
 						position: 'left',
 					},

docs/sidebars.js

@@ -18,6 +18,7 @@ along with web3.js.  If not, see <http://www.gnu.org/licenses/>.
 /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
 const sidebars = {
 	guidesSidebar: [{ type: 'autogenerated', dirName: 'guides' }],
+	docSidebar: [{ type: 'autogenerated', dirName: 'libdocs' }],
 	glossarySidebar: [{ type: 'autogenerated', dirName: 'glossary' }],
 	apiSidebar: [
 		{

package.json

@@ -40,7 +40,8 @@
 		"build:esm": "lerna run build:esm --stream",
 		"build:web": "lerna run build:web --stream",
 		"build:web:analyze": "lerna run build:web:analyze --stream",
-		"build:docs": "cd docs && yarn install && yarn build",
+		"generate:docs": "node ./scripts/docshelper/generatedoc.js",
+		"build:docs": "yarn generate:docs && cd docs && yarn install && yarn build",
 		"changelog": "ts-node -P scripts/changelog/tsconfig.json scripts/changelog/src/index.ts",
 		"clean": "lerna run clean --stream --parallel",
 		"ganache:start": "WEB3_SYSTEM_TEST_BACKEND=ganache && ./scripts/ganache.sh start",
@@ -119,10 +120,12 @@
 		"ts-jest": "^28.0.7",
 		"ts-loader": "^9.3.1",
 		"ts-node": "^10.9.1",
-		"typedoc": "^0.23.9",
+		"typedoc": "^0.25.3",
 		"typedoc-monorepo-link-types": "^0.0.4",
 		"typedoc-plugin-extras": "^2.2.5",
+		"typedoc-plugin-markdown": "^3.17.0",
 		"typedoc-plugin-mdn-links": "^2.0.0",
+		"typedoc-plugin-merge-modules": "^5.1.0",
 		"typescript": "^4.7.4",
 		"utf-8-validate": "^5.0.9",
 		"webpack": "^5.73.0",

packages/web3-eth-accounts/src/account.ts

@@ -15,6 +15,10 @@ You should have received a copy of the GNU Lesser General Public License
 along with web3.js.  If not, see <http://www.gnu.org/licenses/>.
 */
 
+/**
+ * @module Accounts
+ */
+
 import {
 	decrypt as createDecipheriv,
 	encrypt as createCipheriv,
@@ -70,6 +74,7 @@ import type {
 	SignResult,
 } from './types.js';
 
+
 /**
  * Get the private key Uint8Array after the validation
  */

packages/web3-eth-contract/src/contract.ts

@@ -150,6 +150,7 @@ export type ContractMethodsInterface<Abi extends ContractAbi> = {
 } & { [key: string]: ContractBoundMethod<any> };
 
 /**
+ * @hidden
  * The event object can be accessed from `myContract.events.myEvent`.
  *
  * \> Remember: To subscribe to an event, your provider must have support for subscriptions.
@@ -244,7 +245,7 @@ export class Contract<Abi extends ContractAbi>
 
 	private context?: Web3Context;
 	/**
-	 * Creates a new contract instance with all its methods and events defined in its {@doclink glossary/json_interface | json interface} object.
+	 * Creates a new contract instance with all its methods and events defined in its ABI provided.
 	 *
 	 * ```ts
 	 * new web3.eth.Contract(jsonInterface[, address][, options])
@@ -466,7 +467,7 @@ export class Contract<Abi extends ContractAbi>
 	 * });
 	 * ```
 	 *
-	 * @returns - Either returns {@link PayableMethodObject} or {@link NonPayableMethodObject} based on the definitions of the {@doclink glossary/json_interface | json interface} of that contract.
+	 * @returns - Either returns {@link PayableMethodObject} or {@link NonPayableMethodObject} based on the definitions of the ABI of that contract.
 	 */
 	public get methods() {
 		return this._methods;

packages/web3-eth-personal/src/personal.ts

@@ -20,6 +20,9 @@ import { Address, EthPersonalAPI, HexString, Transaction } from 'web3-types';
 
 import * as rpcWrappers from './rpc_method_wrappers.js';
 
+/**
+ * Eth Personal allows you to interact with the Ethereum node’s accounts.
+ */
 export class Personal extends Web3Context<EthPersonalAPI> {
 	/**
 	 *Returns a list of accounts the node controls by using the provider and calling the RPC method personal_listAccounts. Using `web3.eth.accounts.create()` will not add accounts into this list. For that use `web3.eth.personal.newAccount()`.
@@ -143,9 +146,9 @@ export class Personal extends Web3Context<EthPersonalAPI> {
 	/**
 	 * Signs a transaction. This account needs to be unlocked.
 	 * **_NOTE:_** Sending your account password over an unsecured HTTP RPC connection is highly unsecure.
-	 * @param tx - The transaction data to sign. See {@link sendTransaction}  for more information.
+	 * @param tx - The transaction data to sign. See sendTransaction  for more information.
 	 * @param passphrase - The password of the `from` account, to sign the transaction with.
-	 * @returns - The RLP encoded transaction. The `raw` property can be used to send the transaction using {@link sendSignedTransaction}.
+	 * @returns - The RLP encoded transaction. The `raw` property can be used to send the transaction using  sendSignedTransaction.
 	 * @example
 	 * ```ts
 	 * const tx = personal

packages/web3-eth/src/web3_eth.ts

@@ -71,6 +71,10 @@ export const registeredSubscriptions = {
 	newBlockHeaders: NewHeadsSubscription, // the same as newHeads. just for support API like in version 1.x
 };
 
+/**
+ * 
+ * The Web3Eth allows you to interact with an Ethereum blockchain.
+ */
 export class Web3Eth extends Web3Context<Web3EthExecutionAPI, RegisteredSubscription> {
 	public constructor(
 		providerOrContext?: SupportedProviders<any> | Web3ContextInitOptions | string,
@@ -95,7 +99,7 @@ export class Web3Eth extends Web3Context<Web3EthExecutionAPI, RegisteredSubscrip
 		super({
 			...(providerOrContext as Web3ContextInitOptions),
 			registeredSubscriptions,
-		});		
+		});
 	}
 
 	/**

packages/web3-net/src/net.ts

@@ -19,6 +19,9 @@ import { DataFormat, DEFAULT_RETURN_FORMAT, Web3NetAPI } from 'web3-types';
 
 import * as rpcMethodsWrappers from './rpc_method_wrappers.js';
 
+/**
+ * Net class allows you to interact with an Ethereum node’s network properties.
+ */
 export class Net extends Web3Context<Web3NetAPI> {
 	/**
 	 * Gets the current network ID

packages/web3-utils/src/converters.ts

@@ -15,6 +15,10 @@ You should have received a copy of the GNU Lesser General Public License
 along with web3.js.  If not, see <http://www.gnu.org/licenses/>.
 */
 
+/**
+ * @module Utils
+ */
+
 import { keccak256 } from 'ethereum-cryptography/keccak.js';
 import { bytesToUtf8, utf8ToBytes as ecUtf8ToBytes } from 'ethereum-cryptography/utils.js';
 import { Address, Bytes, HexString, Numbers, ValueTypes } from 'web3-types';

packages/web3-utils/src/hash.ts

@@ -15,6 +15,10 @@ You should have received a copy of the GNU Lesser General Public License
 along with web3.js.  If not, see <http://www.gnu.org/licenses/>.
 */
 
+/**
+ * @module Utils
+ */
+
 import { keccak256 } from 'ethereum-cryptography/keccak.js';
 import { utf8ToBytes } from 'ethereum-cryptography/utils.js';
 import {
@@ -46,6 +50,7 @@ import {
 } from './converters.js';
 import { leftPad, rightPad, toTwosComplement } from './string_manipulation.js';
 
+
 const SHA3_EMPTY_BYTES = '0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470';
 
 /**

scripts/docshelper/base.config.js

@@ -0,0 +1,59 @@
+module.exports = {
+    entryPointStrategy: "expand",
+    out: "./docs/docs/libdocs/",
+
+    // "exclude": [
+    //     "**/*.test.ts"
+    // ],
+    plugin: [
+        "typedoc-plugin-markdown",
+        "typedoc-plugin-merge-modules"
+    ],
+
+    mergeModulesRenameDefaults: true, // NEW option of TypeDoc added by typedoc-plugin-merge-modules plugin
+
+    hideInPageTOC: true,
+    hideBreadcrumbs: true,
+    hidePageTitle: true,
+
+    //publicPath: "https://docs.web3js.org/libdocs/",
+    //filenameSeparator : "-",
+    //indexTitle: "",
+    //preserveAnchorCasing: true,
+
+    excludeExternals: true,
+    excludeReferences: true,
+    tsconfig: "./docs/tsconfig.docs.json",
+    excludeNotDocumented: true,
+
+    excludeNotDocumentedKinds: [
+        "Namespace",
+        "Enum",
+        "EnumMember",
+        "Variable",
+        "Function",
+        "Class",
+        "Interface",
+        "Constructor",
+        "Property",
+        "Method",
+        "CallSignature",
+        "IndexSignature",
+        "ConstructorSignature",
+        "Accessor",
+        "GetSignature",
+        "SetSignature",
+        "TypeAlias",
+        "Reference"
+    ],
+    excludeInternal: true,
+    excludePrivate: true,
+    excludeProtected: true,
+
+    visibilityFilters: {
+        "protected": false,
+        "private": false,
+        "inherited": false,
+        "external": false
+    }
+};

scripts/docshelper/classesdoc.config.js

@@ -0,0 +1,20 @@
+const baseDocConfig = require('./base.config.js');
+
+module.exports = {
+    ... baseDocConfig,
+
+    entryPoints: [
+        "./packages/web3-eth/src/web3_eth.ts",
+        "./packages/web3-eth-accounts/src/wallet.ts",
+        "./packages/web3-eth-accounts/src/account.ts",
+        "./packages/web3-eth-contract/src/contract.ts",
+        "./packages/web3-eth-ens/src/ens.ts",
+        "./packages/web3-eth-iban/src/iban.ts",
+        "./packages/web3-eth-personal/src/personal.ts",
+        "./packages/web3-net/src/net.ts",
+    ],
+
+    excludeCategories: "ContractEvent", // for exluding being in module.md file and invalid link in contract.md
+    mergeModulesMergeMode: "project", // NEW option of TypeDoc added by typedoc-plugin-merge-modules plugin
+
+};

scripts/docshelper/functionsdoc.config.js

@@ -0,0 +1,17 @@
+
+const baseConfig = require('./base.config.js');
+
+module.exports =  {
+    ... baseConfig,
+
+    entryPoints: [
+        "./packages/web3-eth-accounts/src/account.ts",
+        //utils
+        "./packages/web3-utils/src/converters.ts",
+        "./packages/web3-utils/src/hash.ts"
+    ],
+
+    mergeModulesMergeMode: "module", // NEW option of TypeDoc added by typedoc-plugin-merge-modules plugin
+    cleanOutputDir: false,
+
+};