Things I wish I knew... (#1374)

* Make a start

* Intro

* Installation

* Flatten

* Move METHODS_*.md to substrate/*.md

* Basics

* Apply suggestions from code review

Co-Authored-By: Thibaut Sardan <33178835+Tbaut@users.noreply.github.com>

* Substrate links

* Create

* api.consts

* Typo

* Typo, ms -> md

* types.basics (SIP)

* Type basics

* api.consts jumps to api.query

* Start to api.query

* Basic queries

* Point starting to actual overview

* api.rpc

* Derive detour

* Query subs & query multi

* Apply suggestions from code review

Co-Authored-By: Thibaut Sardan <33178835+Tbaut@users.noreply.github.com>

* typo

* Query extras

* Basic transactions

* Misplaced ,

* keyring WIP

* Keyring wrap-up

* Subs SIP

* tx subs more WIP

* tx subs

* Small types cleanups

* Apply suggested changes from @JoshOrndorff

* Clarify naked await

* tx wrapping WIP

* Wrap api.wrap

* TS placeholder

* [WIP] markers for not-started

* Clarifying comments

* Additional clarifications

* types.extend... well, extended...

* Remove *nix

* Warp up TypeScript... it is it (for now)

* Some small text clarifications

* Some cleanups

* Cleanups, typos

* keyring cleanups

* Cleanups

* Wrap

* api.wrap wrapped... hopefully

* typos

* Registration typos

* typescript typos, hope I caught most...

packages/api/README.md

@@ -7,13 +7,13 @@ The API wrappers provide a standard interface for use -
 - A static `.create(<optional ApiOptions>)` that returns an API instance when connected, decorated and ready-to use. ApiOptions can include an optional WsProvider and optional custom type definitions `{ provider: <Optional WsProvider>, types: <Optional RegistryTypes> }`.
 - The above is just a wrapper for `new Api(<optional ApiOptions>) `, exposing the `isReady` getter
 - `api.rpc.<section>.<method>` provides access to actual RPC calls, be it for queries, submission or retrieving chain information
-  - [RPC (node interface)](../METHODS_RPC.md)
+  - [RPC (node interface)](../substrate/rpc.md)
 - `api.query.<section>.<method>` provides access to chain state queries. These are dynamically populated based on what the runtime provides
-  - [Storage chain state (runtime node interface)](../METHODS_STORAGE.md)
+  - [Storage chain state (runtime node interface)](../substrate/storage.md)
 - `api.tx.<section>.<method>` provides the ability to create a transaction, like chain state, this list is populated from a runtime query
-  - [Extrinsics (runtime node interface)](../METHODS_EXTRINSICS.md)
+  - [Extrinsics (runtime node interface)](../substrate/extrinsics.md)
 - `api.consts.<section>.<constant>` provides access to the module constants (parameter types).
-  - [Constants (runtime node interface)](../METHODS_CONSTANTS.md)
+  - [Constants (runtime node interface)](../substrate/constants.md)
 
 ## API Selection
 

packages/api/src/base/index.ts

@@ -88,7 +88,7 @@ export default abstract class ApiBase<ApiType> extends Init<ApiType> {
   }
 
   /**
-   * @description  Returns th version of extrinsics in-use on this chain
+   * @description  Returns the version of extrinsics in-use on this chain
    */
   public get extrinsicVersion (): number {
     return this._extrinsicType;

packages/type-jsonrpc/README.md

@@ -2,7 +2,7 @@
 
 A definition of all the methods exposed in a general Polkadot client application. These are used not only to provide a comprehensive code-generated document of the available methods, but are also used in the API to auto-generate endpoints with the required type-checking.
 
-For a list of currently exposed methods, see the [method documentation](docs/METHODS_RPC.md).
+For a list of currently exposed methods, see the [method documentation](docs/substrate/rpc.md).
 
 ## Usage
 

packages/types/src/scripts/METHODS_STORAGE_SUBSTRATE.md

@@ -1,23 +0,0 @@
-
----
-
-### substrate
-
-_These are keys that are always available to the runtime implementation_
-
-▸ **changesTrieConfig**(): `u32`
-- **summary**: Changes trie configuration is stored under this key.
-
-▸ **childStorageKeyPrefix**(): `u32`
-- **summary**: Prefix of child storage keys.
-
-▸ **code**(): `Bytes`
-- **summary**: Wasm code of the runtime.
-
-▸ **extrinsicIndex**(): `u32`
-- **summary**: Current extrinsic index (u32) is stored under this key.
-
-▸ **heapPages**(): `u64`
-- **summary**: Number of wasm linear memory pages required for execution of the runtime.
-
----

packages/types/src/scripts/MetadataMd.ts

@@ -16,11 +16,13 @@ import MetadataV7, { ModuleMetadataV7 } from '../Metadata/v7';
 const ANCHOR_TOP = '';
 const LINK_BACK_TO_TOP = '';
 
-const DESC_CONSTANTS = '\n\n_The following sections contain the module constants, also known as parameter types.\n';
-const DESC_EXTRINSICS = '\n\n_The following sections contain Extrinsics methods are part of the default Substrate runtime._\n';
-const DESC_EVENTS = '\n\nEvents are emitted for certain operations on the runtime. The following sections describe the events that are part of the default Substrate runtime.\n';
-const DESC_RPC = '\n\n_The following sections contain RPC methods that are Remote Calls available by default and allow you to interact with the actual node, query, and submit. The RPCs are provided by Substrate itself._';
-const DESC_STORAGE = '\n\n_The following sections contain Storage methods are part of the default Substrate runtime._\n';
+const STATIC_TEXT = '\n\n(NOTE: These were generated from a static/snapshot view of a recent Substrate master node. Some items may not be available in older nodes, or in any customized implementations.)';
+
+const DESC_CONSTANTS = `\n\nThe following sections contain the module constants, also known as parameter types. These can only be changed as part of a runtime upgrade. On the api, these are exposed via \`api.consts.<module>.<method>\`. ${STATIC_TEXT}\n`;
+const DESC_EXTRINSICS = `\n\nThe following sections contain Extrinsics methods are part of the default Substrate runtime. On the api, these are exposed via \`api.tx.<module>.<method>\`. ${STATIC_TEXT}\n`;
+const DESC_EVENTS = `\n\nEvents are emitted for certain operations on the runtime. The following sections describe the events that are part of the default Substrate runtime. ${STATIC_TEXT}\n`;
+const DESC_RPC = '\n\nThe following sections contain RPC methods that are Remote Calls available by default and allow you to interact with the actual node, query, and submit.\n';
+const DESC_STORAGE = `\n\nThe following sections contain Storage methods are part of the default Substrate runtime. On the api, these are exposed via \`api.query.<module>.<method>\`. ${STATIC_TEXT}\n`;
 
 function sectionLink (sectionName: string): string {
   return `- **[${stringCamelCase(sectionName)}](#${stringCamelCase(sectionName)})**\n\n`;
@@ -219,26 +221,26 @@ function writeFile (name: string, ...chunks: any[]): void {
 }
 
 function writeToRpcMd (): void {
-  writeFile('docs/METHODS_RPC.md', addRpc());
+  writeFile('docs/substrate/rpc.md', addRpc());
 }
 
 function writeToConstantsMd (metadata: MetadataV7): void {
-  writeFile('docs/METHODS_CONSTANTS.md', addConstants(metadata));
+  writeFile('docs/substrate/constants.md', addConstants(metadata));
 }
 
 function writeToStorageMd (metadata: MetadataV7): void {
   const options = { flags: 'r', encoding: 'utf8' };
-  const data = fs.readFileSync('packages/types/src/scripts/METHODS_STORAGE_SUBSTRATE.md', options);
+  const data = fs.readFileSync('docs/substrate/storage-known.md', options);
 
-  writeFile('docs/METHODS_STORAGE.md', addStorage(metadata), data);
+  writeFile('docs/substrate/storage.md', addStorage(metadata), data);
 }
 
 function writeToExtrinsicsMd (metadata: MetadataV7): void {
-  writeFile('docs/METHODS_EXTRINSICS.md', addExtrinsics(metadata));
+  writeFile('docs/substrate/extrinsics.md', addExtrinsics(metadata));
 }
 
 function writeToEventsMd (metadata: MetadataV7): void {
-  writeFile('docs/METHODS_EVENTS.md', addEvents(metadata));
+  writeFile('docs/substrate/events.md', addEvents(metadata));
 }
 
 const metadata = new Metadata(rpcdata).asLatest;