From 99b9332dfb8bce4cccc32221f36c70508e0f6101 Mon Sep 17 00:00:00 2001 From: Luke Schoen Date: Mon, 15 Oct 2018 23:35:26 +0200 Subject: [PATCH] fix: Fixes #289. Add Anchor links to Sections on Node interface pages Rpc, Storage, Extrinsics (#302) * fix: Fixes #289. Add Anchor links to Sections on Node interfaces pages RPC, Storage, Extrinsics * refactor: Add reusable functions to generate section links/header. Add constants for back to top link/anchor * Add function with switch to generate section links to section anchors. * Add common function to generate section header. * Reuse common Anchor/Link HTML with constants. * refactor: Rename generateAnchors to generateSectionLinks. Add reusable function for section link text --- packages/types/src/scripts/MetadataMd.ts | 60 +++++++++++++++++++----- 1 file changed, 48 insertions(+), 12 deletions(-) diff --git a/packages/types/src/scripts/MetadataMd.ts b/packages/types/src/scripts/MetadataMd.ts index 0db606eb1b..14bfc092d2 100644 --- a/packages/types/src/scripts/MetadataMd.ts +++ b/packages/types/src/scripts/MetadataMd.ts @@ -10,17 +10,51 @@ import Metadata from '../Metadata'; import rpcdata from '../Metadata.rpc'; import Method from '../Method'; +const ANCHOR_TOP = ``; +const LINK_BACK_TO_TOP = `Back To Top`; + // some intro text goes in here -const DESC_RPC = '\n\n_The following RPC methods are the Remote Calls that are available by default and allow you to interact with the actual node, query, and submit. The RPCs are provided by Substrate itself. The RPCs are never exposed by the runtime._'; -const DESC_EXTRINSICS = '\n\n_The following Extrinsics methods are part of the default Substrate runtime. Since an Extrinsic is a holder of an object that is just an array of bytes to be included, it does not have a return._'; -const DESC_STORAGE = '\n\n_The following Storage methods are part of the default Substrate runtime._'; +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. The RPCs are never exposed by the runtime._'; +const DESC_EXTRINSICS = '\n\n_The following sections contain Extrinsics methods are part of the default Substrate runtime. Since an Extrinsic is a holder of an object that is just an array of bytes to be included, it does not have a return._\n'; +const DESC_STORAGE = '\n\n_The following sections contain Storage methods are part of the default Substrate runtime._\n'; + +function sectionLink (sectionName: string) { + return `- **[${stringCamelCase(sectionName)}](#${stringCamelCase(sectionName)})**\n\n`; +} + +function generateSectionLinks (sectionName: string, metadata?: any) { + switch (sectionName) { + case 'rpc': { + return Object.keys(interfaces) + .sort().map((sectionName) => sectionLink(sectionName)).join(''); + } + case 'extrinsics': + case 'storage': { + return metadata.modules.raw + .sort().map((runtimeModuleMetadata: any) => { + const sectionName = runtimeModuleMetadata.raw.prefix.raw; + + return sectionLink(sectionName); + }).join(''); + } + default: { + console.error('Unknown section name provided to generate anchors'); + break; + } + } +} + +function generateSectionHeader (md: string, sectionName: string) { + return `${md}\n___\n${LINK_BACK_TO_TOP}\n\n### ${sectionName}\n`; +} function addRpc () { - const renderHeading = `## JSON-RPC${DESC_RPC}\n`; + const renderHeading = `## ${ANCHOR_TOP}JSON-RPC${DESC_RPC}\n`; + const renderAnchors = generateSectionLinks('rpc'); return Object.keys(interfaces).reduce((md, sectionName) => { const section = interfaces[sectionName]; - const renderSection = `${md}\n___\n\n### ${sectionName}\n\n_${section.description}_\n`; + const renderSection = generateSectionHeader(md, sectionName) + `\n_${section.description}_\n`; return Object.keys(section.methods).reduce((md, methodName) => { const method = section.methods[methodName]; @@ -37,11 +71,12 @@ function addRpc () { return isSub ? `${renderSignatureSub}${renderSummary}` : `${renderSignature}${renderSummary}`; }, renderSection); - }, renderHeading); + }, renderHeading + renderAnchors); } function addExtrinsics (metadata: any) { - const renderHeading = `## Extrinsics${DESC_EXTRINSICS}`; + const renderHeading = `## ${ANCHOR_TOP}Extrinsics${DESC_EXTRINSICS}`; + const renderAnchors = generateSectionLinks('extrinsics', metadata); return metadata.modules.reduce((md: string, meta: any) => { if (!meta.module.call || !meta.module.call.functions.length) { @@ -49,7 +84,7 @@ function addExtrinsics (metadata: any) { } const sectionName = stringCamelCase(meta.prefix.toString()); - const renderSection = `${md}\n___\n### ${sectionName}\n`; + const renderSection = generateSectionHeader(md, sectionName); return meta.module.call.functions.reduce((md: string, func: any) => { const methodName = stringCamelCase(func.name.toString()); @@ -60,11 +95,12 @@ function addExtrinsics (metadata: any) { return renderSignature + renderSummary; }, renderSection); - }, renderHeading); + }, renderHeading + renderAnchors); } function addStorage (metadata: any) { - const renderHeading = `## Storage${DESC_STORAGE}`; + const renderHeading = `## ${ANCHOR_TOP}Storage${DESC_STORAGE}`; + const renderAnchors = generateSectionLinks('storage', metadata); return metadata.modules.reduce((md: string, moduleMetadata: any) => { if (!moduleMetadata.storage) { @@ -72,7 +108,7 @@ function addStorage (metadata: any) { } const sectionName = stringLowerFirst(moduleMetadata.storage.prefix.toString()); - const renderSection = `${md}\n___\n### ${sectionName}\n`; + const renderSection = generateSectionHeader(md, sectionName); return moduleMetadata.storage.functions.reduce((md: string, func: any) => { const methodName = stringLowerFirst(func.name.toString()); @@ -83,7 +119,7 @@ function addStorage (metadata: any) { return renderSignature + renderSummary; }, renderSection); - }, renderHeading); + }, renderHeading + renderAnchors); } function metadataStorageMethodsAsText () {