Add ability to nest doc ref markdown under specific versions

packages/react-docs-example/ts/docs.tsx

@@ -14,7 +14,7 @@ import * as v0TypeDocJson from './json/0.1.12.json';
 import * as v2TypeDocJson from './json/0.2.0.json';
 
 // tslint:disable-next-line:no-implicit-dependencies no-var-requires
-const IntroMarkdown = require('md/introduction');
+const IntroMarkdownV1 = require('md/introduction');
 
 const docSections = {
     introduction: 'introduction',
@@ -32,8 +32,10 @@ const docsInfoConfig: DocsInfoConfig = {
         web3Wrapper: [docSections.web3Wrapper],
         types: [docSections.types],
     },
-    sectionNameToMarkdown: {
-        [docSections.introduction]: IntroMarkdown,
+    sectionNameToMarkdownByVersion: {
+        '0.0.1': {
+            [docSections.introduction]: IntroMarkdownV1,
+        },
     },
     sectionNameToModulePath: {
         [docSections.web3Wrapper]: ['"web3-wrapper/src/index"'],

packages/react-docs/CHANGELOG.json

@@ -1,4 +1,12 @@
 [
+    {
+        "version": "0.0.15",
+        "changes": [
+            {
+                "note": "Nest MD files under versions so that you can update them for future versions"
+            }
+        ]
+    },
     {
         "timestamp": 1529397769,
         "version": "0.0.14",

packages/react-docs/package.json

@@ -52,7 +52,8 @@
         "react-dom": "15.6.1",
         "react-markdown": "^3.2.2",
         "react-scroll": "^1.5.2",
-        "react-tooltip": "^3.2.7"
+        "react-tooltip": "^3.2.7",
+        "semver": "5.5.0"
     },
     "publishConfig": {
         "access": "public"

packages/react-docs/src/components/documentation.tsx

@@ -12,6 +12,7 @@ import {
 import * as _ from 'lodash';
 import CircularProgress from 'material-ui/CircularProgress';
 import * as React from 'react';
+import * as semver from 'semver';
 
 import { DocsInfo } from '../docs_info';
 import {
@@ -180,7 +181,14 @@ export class Documentation extends React.Component<DocumentationProps, Documenta
         return renderedSections;
     }
     private _renderSection(typeDefinitionByName: TypeDefinitionByName, sectionName: string): React.ReactNode {
-        const markdownFileIfExists = this.props.docsInfo.sectionNameToMarkdown[sectionName];
+        const markdownVersions = _.keys(this.props.docsInfo.sectionNameToMarkdownByVersion);
+        // Get version LTE to selectedVersion
+        const eligibleVersions = _.filter(markdownVersions, mdVersion => {
+            return semver.lte(mdVersion, this.props.selectedVersion);
+        });
+        const sortedEligibleVersions = eligibleVersions.sort(semver.rcompare.bind(semver));
+        const closestVersion = sortedEligibleVersions[0];
+        const markdownFileIfExists = this.props.docsInfo.sectionNameToMarkdownByVersion[closestVersion][sectionName];
         if (!_.isUndefined(markdownFileIfExists)) {
             return (
                 <MarkdownSection

packages/react-docs/src/docs_info.ts

@@ -24,7 +24,7 @@ export class DocsInfo {
     public packageUrl: string;
     public menu: DocsMenu;
     public sections: SectionsMap;
-    public sectionNameToMarkdown: { [sectionName: string]: string };
+    public sectionNameToMarkdownByVersion: SectionNameToMarkdownByVersion;
     public contractsByVersionByNetworkId?: ContractsByVersionByNetworkId;
     public typeConfigs: DocsInfoTypeConfigs;
     private _docsInfo: DocsInfoConfig;
@@ -34,7 +34,7 @@ export class DocsInfo {
         this.displayName = config.displayName;
         this.packageUrl = config.packageUrl;
         this.sections = config.sections;
-        this.sectionNameToMarkdown = config.sectionNameToMarkdown;
+        this.sectionNameToMarkdownByVersion = config.sectionNameToMarkdownByVersion;
         this.contractsByVersionByNetworkId = config.contractsByVersionByNetworkId;
         this.typeConfigs = config.typeConfigs;
         this._docsInfo = config;

packages/react-docs/src/types.ts

@@ -1,3 +1,7 @@
+export interface SectionNameToMarkdownByVersion {
+    [version: string]: { [sectionName: string]: string };
+}
+
 export interface DocsInfoConfig {
     id: string;
     type: SupportedDocJson;
@@ -5,7 +9,7 @@ export interface DocsInfoConfig {
     packageUrl: string;
     menu: DocsMenu;
     sections: SectionsMap;
-    sectionNameToMarkdown: { [sectionName: string]: string };
+    sectionNameToMarkdownByVersion: SectionNameToMarkdownByVersion;
     visibleConstructors: string[];
     sectionNameToModulePath?: { [sectionName: string]: string[] };
     menuSubsectionToVersionWhenIntroduced?: { [sectionName: string]: string };

packages/sol-compiler/package.json

@@ -91,7 +91,7 @@
         "lodash": "^4.17.4",
         "mkdirp": "^0.5.1",
         "require-from-string": "^2.0.1",
-        "semver": "^5.5.0",
+        "semver": "5.5.0",
         "solc": "^0.4.23",
         "web3-eth-abi": "^1.0.0-beta.24",
         "yargs": "^10.0.3"

packages/website/ts/containers/connect_documentation.ts

@@ -10,8 +10,8 @@ import { constants } from 'ts/utils/constants';
 import { Translate } from 'ts/utils/translate';
 
 /* tslint:disable:no-var-requires */
-const IntroMarkdown = require('md/docs/connect/introduction');
-const InstallationMarkdown = require('md/docs/connect/installation');
+const IntroMarkdownV1 = require('md/docs/connect/1.0.0/introduction');
+const InstallationMarkdownV1 = require('md/docs/connect/1.0.0/installation');
 /* tslint:enable:no-var-requires */
 
 const connectDocSections = {
@@ -34,9 +34,11 @@ const docsInfoConfig: DocsInfoConfig = {
         webSocketOrderbookChannel: [connectDocSections.webSocketOrderbookChannel],
         types: [connectDocSections.types],
     },
-    sectionNameToMarkdown: {
-        [connectDocSections.introduction]: IntroMarkdown,
-        [connectDocSections.installation]: InstallationMarkdown,
+    sectionNameToMarkdownByVersion: {
+        '0.0.1': {
+            [connectDocSections.introduction]: IntroMarkdownV1,
+            [connectDocSections.installation]: InstallationMarkdownV1,
+        },
     },
     sectionNameToModulePath: {
         [connectDocSections.httpClient]: ['"src/http_client"'],

packages/website/ts/containers/ethereum_types_documentation.ts

@@ -30,9 +30,11 @@ const docsInfoConfig: DocsInfoConfig = {
         install: [docSections.installation],
         types: [docSections.types],
     },
-    sectionNameToMarkdown: {
-        [docSections.introduction]: IntroMarkdown,
-        [docSections.installation]: InstallationMarkdown,
+    sectionNameToMarkdownByVersion: {
+        '0.0.1': {
+            [docSections.introduction]: IntroMarkdown,
+            [docSections.installation]: InstallationMarkdown,
+        },
     },
     sectionNameToModulePath: {
         [docSections.types]: ['"index"'],

packages/website/ts/containers/json_schemas_documentation.ts

@@ -9,10 +9,10 @@ import { DocPackages } from 'ts/types';
 import { Translate } from 'ts/utils/translate';
 
 /* tslint:disable:no-var-requires */
-const IntroMarkdown = require('md/docs/json_schemas/introduction');
-const InstallationMarkdown = require('md/docs/json_schemas/installation');
-const UsageMarkdown = require('md/docs/json_schemas/usage');
-const SchemasMarkdown = require('md/docs/json_schemas/schemas');
+const IntroMarkdownV1 = require('md/docs/json_schemas/1.0.0/introduction');
+const InstallationMarkdownV1 = require('md/docs/json_schemas/1.0.0/installation');
+const UsageMarkdownV1 = require('md/docs/json_schemas/1.0.0/usage');
+const SchemasMarkdownV1 = require('md/docs/json_schemas/1.0.0/schemas');
 /* tslint:enable:no-var-requires */
 
 const docSections = {
@@ -35,11 +35,13 @@ const docsInfoConfig: DocsInfoConfig = {
         schemaValidator: [docSections.schemaValidator],
         schemas: [docSections.schemas],
     },
-    sectionNameToMarkdown: {
-        [docSections.introduction]: IntroMarkdown,
-        [docSections.installation]: InstallationMarkdown,
-        [docSections.schemas]: SchemasMarkdown,
-        [docSections.usage]: UsageMarkdown,
+    sectionNameToMarkdownByVersion: {
+        '0.0.1': {
+            [docSections.introduction]: IntroMarkdownV1,
+            [docSections.installation]: InstallationMarkdownV1,
+            [docSections.schemas]: SchemasMarkdownV1,
+            [docSections.usage]: UsageMarkdownV1,
+        },
     },
     sectionNameToModulePath: {
         [docSections.schemaValidator]: ['"json-schemas/src/schema_validator"'],

packages/website/ts/containers/order_utils_documentation.ts

@@ -10,8 +10,8 @@ import { constants } from 'ts/utils/constants';
 import { Translate } from 'ts/utils/translate';
 
 /* tslint:disable:no-var-requires */
-const IntroMarkdown = require('md/docs/order_utils/introduction');
-const InstallationMarkdown = require('md/docs/order_utils/installation');
+const IntroMarkdownV1 = require('md/docs/order_utils/1.0.0/introduction');
+const InstallationMarkdownV1 = require('md/docs/order_utils/1.0.0/installation');
 /* tslint:enable:no-var-requires */
 
 const docSections = {
@@ -32,9 +32,11 @@ const docsInfoConfig: DocsInfoConfig = {
         usage: [docSections.usage],
         types: [docSections.types],
     },
-    sectionNameToMarkdown: {
-        [docSections.introduction]: IntroMarkdown,
-        [docSections.installation]: InstallationMarkdown,
+    sectionNameToMarkdownByVersion: {
+        '0.0.1': {
+            [docSections.introduction]: IntroMarkdownV1,
+            [docSections.installation]: InstallationMarkdownV1,
+        },
     },
     sectionNameToModulePath: {
         [docSections.usage]: [

packages/website/ts/containers/smart_contracts_documentation.ts

@@ -10,7 +10,7 @@ import { DocPackages, SmartContractDocSections as Sections } from 'ts/types';
 import { Translate } from 'ts/utils/translate';
 
 /* tslint:disable:no-var-requires */
-const IntroMarkdown = require('md/docs/smart_contracts/introduction');
+const IntroMarkdownV1 = require('md/docs/smart_contracts/1.0.0/introduction');
 /* tslint:enable:no-var-requires */
 
 const docsInfoConfig: DocsInfoConfig = {
@@ -22,8 +22,10 @@ const docsInfoConfig: DocsInfoConfig = {
         introduction: [Sections.Introduction],
         contracts: [Sections.Exchange, Sections.TokenRegistry, Sections.ZRXToken, Sections.TokenTransferProxy],
     },
-    sectionNameToMarkdown: {
-        [Sections.Introduction]: IntroMarkdown,
+    sectionNameToMarkdownByVersion: {
+        '0.0.1': {
+            [Sections.Introduction]: IntroMarkdownV1,
+        },
     },
     sections: {
         Introduction: Sections.Introduction,

packages/website/ts/containers/sol_compiler_documentation.ts

@@ -9,8 +9,8 @@ import { DocPackages } from 'ts/types';
 import { Translate } from 'ts/utils/translate';
 
 /* tslint:disable:no-var-requires */
-const IntroMarkdown = require('md/docs/sol-compiler/introduction');
-const InstallationMarkdown = require('md/docs/sol-compiler/installation');
+const IntroMarkdownV1 = require('md/docs/sol-compiler/introduction');
+const InstallationMarkdownV1 = require('md/docs/sol-compiler/installation');
 const UsageMarkdown = require('md/docs/sol-compiler/usage');
 /* tslint:enable:no-var-requires */
 
@@ -34,10 +34,12 @@ const docsInfoConfig: DocsInfoConfig = {
         compiler: [docSections.compiler],
         types: [docSections.types],
     },
-    sectionNameToMarkdown: {
-        [docSections.introduction]: IntroMarkdown,
-        [docSections.installation]: InstallationMarkdown,
-        [docSections.usage]: UsageMarkdown,
+    sectionNameToMarkdownByVersion: {
+        '0.0.1': {
+            [docSections.introduction]: IntroMarkdownV1,
+            [docSections.installation]: InstallationMarkdownV1,
+            [docSections.usage]: UsageMarkdown,
+        },
     },
     sectionNameToModulePath: {
         [docSections.compiler]: ['"sol-compiler/src/compiler"'],

packages/website/ts/containers/sol_cov_documentation.ts

@@ -9,8 +9,8 @@ import { DocPackages } from 'ts/types';
 import { Translate } from 'ts/utils/translate';
 
 /* tslint:disable:no-var-requires */
-const IntroMarkdown = require('md/docs/sol_cov/introduction');
-const InstallationMarkdown = require('md/docs/sol_cov/installation');
+const IntroMarkdownV1 = require('md/docs/sol_cov/introduction');
+const InstallationMarkdownV1 = require('md/docs/sol_cov/installation');
 const UsageMarkdown = require('md/docs/sol_cov/usage');
 /* tslint:enable:no-var-requires */
 
@@ -40,10 +40,12 @@ const docsInfoConfig: DocsInfoConfig = {
         'truffle-artifact-adapter': [docSections.truffleArtifactAdapter],
         types: [docSections.types],
     },
-    sectionNameToMarkdown: {
-        [docSections.introduction]: IntroMarkdown,
-        [docSections.installation]: InstallationMarkdown,
-        [docSections.usage]: UsageMarkdown,
+    sectionNameToMarkdownByVersion: {
+        '0.0.1': {
+            [docSections.introduction]: IntroMarkdownV1,
+            [docSections.installation]: InstallationMarkdownV1,
+            [docSections.usage]: UsageMarkdown,
+        },
     },
     sectionNameToModulePath: {
         [docSections.coverageSubprovider]: ['"sol-cov/src/coverage_subprovider"'],

packages/website/ts/containers/subproviders_documentation.ts

@@ -10,8 +10,8 @@ import { constants } from 'ts/utils/constants';
 import { Translate } from 'ts/utils/translate';
 
 /* tslint:disable:no-var-requires */
-const IntroMarkdown = require('md/docs/subproviders/introduction');
-const InstallationMarkdown = require('md/docs/subproviders/installation');
+const IntroMarkdownV1 = require('md/docs/subproviders/introduction');
+const InstallationMarkdownV1 = require('md/docs/subproviders/installation');
 const LedgerNodeHidMarkdown = require('md/docs/subproviders/ledger_node_hid');
 /* tslint:enable:no-var-requires */
 
@@ -57,10 +57,12 @@ const docsInfoConfig: DocsInfoConfig = {
         ['nonceTracker-subprovider']: [docSections.nonceTrackerSubprovider],
         types: [docSections.types],
     },
-    sectionNameToMarkdown: {
-        [docSections.introduction]: IntroMarkdown,
-        [docSections.installation]: InstallationMarkdown,
-        [docSections.ledgerNodeHid]: LedgerNodeHidMarkdown,
+    sectionNameToMarkdownByVersion: {
+        '0.0.1': {
+            [docSections.introduction]: IntroMarkdownV1,
+            [docSections.installation]: InstallationMarkdownV1,
+            [docSections.ledgerNodeHid]: LedgerNodeHidMarkdown,
+        },
     },
     sectionNameToModulePath: {
         [docSections.subprovider]: ['"subproviders/src/subproviders/subprovider"'],

packages/website/ts/containers/web3_wrapper_documentation.ts

@@ -10,8 +10,8 @@ import { constants } from 'ts/utils/constants';
 import { Translate } from 'ts/utils/translate';
 
 /* tslint:disable:no-var-requires */
-const IntroMarkdown = require('md/docs/web3_wrapper/introduction');
-const InstallationMarkdown = require('md/docs/web3_wrapper/installation');
+const IntroMarkdownV1 = require('md/docs/web3_wrapper/introduction');
+const InstallationMarkdownV1 = require('md/docs/web3_wrapper/installation');
 /* tslint:enable:no-var-requires */
 
 const docSections = {
@@ -32,9 +32,11 @@ const docsInfoConfig: DocsInfoConfig = {
         web3Wrapper: [docSections.web3Wrapper],
         types: [docSections.types],
     },
-    sectionNameToMarkdown: {
-        [docSections.introduction]: IntroMarkdown,
-        [docSections.installation]: InstallationMarkdown,
+    sectionNameToMarkdownByVersion: {
+        '0.0.1': {
+            [docSections.introduction]: IntroMarkdownV1,
+            [docSections.installation]: InstallationMarkdownV1,
+        },
     },
     sectionNameToModulePath: {
         [docSections.web3Wrapper]: ['"web3-wrapper/src/web3_wrapper"'],

packages/website/ts/containers/zero_ex_js_documentation.ts

@@ -10,11 +10,11 @@ import { constants } from 'ts/utils/constants';
 import { Translate } from 'ts/utils/translate';
 
 /* tslint:disable:no-var-requires */
-const IntroMarkdown = require('md/docs/0xjs/introduction');
-const InstallationMarkdown = require('md/docs/0xjs/installation');
-const AsyncMarkdown = require('md/docs/0xjs/async');
-const ErrorsMarkdown = require('md/docs/0xjs/errors');
-const versioningMarkdown = require('md/docs/0xjs/versioning');
+const IntroMarkdownV1 = require('md/docs/0xjs/1.0.0/introduction');
+const InstallationMarkdownV1 = require('md/docs/0xjs/1.0.0/installation');
+const AsyncMarkdownV1 = require('md/docs/0xjs/1.0.0/async');
+const ErrorsMarkdownV1 = require('md/docs/0xjs/1.0.0/errors');
+const versioningMarkdownV1 = require('md/docs/0xjs/1.0.0/versioning');
 /* tslint:enable:no-var-requires */
 
 const zeroExJsDocSections = {
@@ -54,12 +54,14 @@ const docsInfoConfig: DocsInfoConfig = {
         orderWatcher: [zeroExJsDocSections.orderWatcher],
         types: [zeroExJsDocSections.types],
     },
-    sectionNameToMarkdown: {
-        [zeroExJsDocSections.introduction]: IntroMarkdown,
-        [zeroExJsDocSections.installation]: InstallationMarkdown,
-        [zeroExJsDocSections.async]: AsyncMarkdown,
-        [zeroExJsDocSections.errors]: ErrorsMarkdown,
-        [zeroExJsDocSections.versioning]: versioningMarkdown,
+    sectionNameToMarkdownByVersion: {
+        '0.0.1': {
+            [zeroExJsDocSections.introduction]: IntroMarkdownV1,
+            [zeroExJsDocSections.installation]: InstallationMarkdownV1,
+            [zeroExJsDocSections.async]: AsyncMarkdownV1,
+            [zeroExJsDocSections.errors]: ErrorsMarkdownV1,
+            [zeroExJsDocSections.versioning]: versioningMarkdownV1,
+        },
     },
     sectionNameToModulePath: {
         [zeroExJsDocSections.zeroEx]: ['"0x.js/src/0x"', '"src/0x"'],