New documentation setup (#1118)

* initial conversion of guides to asciidoc

* add initial structure for antora

(cherry picked from commit 0e9c79c)

* fix heading levels

* add script for local authoring

* set correct docs start page

* revert silencing http server

* make component name shorter

* update docsite script

* change cli docs generator for asciidoc

* add initial version of cli and lib docs

* fix asciidoc admonitions

* remove docs for previous versions

packages/cli/.eslintrc.js

@@ -2,4 +2,7 @@ module.exports = {
   extends: [
       '../../.eslintrc.base.js',
   ],
-};
+  rules: {
+    '@typescript-eslint/explicit-function-return-type': false,
+  },
+};

packages/cli/docs/bin/docs.ts

@@ -1,62 +1,60 @@
 #!/usr/bin/env node
 
-import React from 'react';
 import program from '../../src/bin/program';
-import { renderToStaticMarkup } from 'react-dom/server';
-import { writeFileSync, existsSync, mkdirSync } from 'fs';
-import Main from '../components/Main';
-import Command from '../components/Command';
+import { writeFileSync } from 'fs';
+import { ensureDirSync } from 'fs-extra';
 import path from 'path';
 import process from 'process';
 
-const outputPath = 'docs/build';
+const outputPath = '../docs/modules/cli';
 
-function formatContent(id, title, content) {
-  return `---
-id: cli_${id}
-title: ${title}
----
+function render(cmd) {
+  const description = cmd.description() || '';
+  const options = cmd.options.map(o => `\`${o.flags}\`:: ${o.description}`).join('\n');
 
-${content}
+  return `\
+== ${cmd.name()}
+
+Usage: \`${cmd.name()} ${cmd.usage()}\`
+
+${description}
+
+${options}
 `;
 }
 
-function writeMd(id, title, content) {
-  const data = formatContent(id, title, content);
-  writeFileSync(path.resolve(outputPath, `cli_${id}.md`), data);
+function writeAdoc(id, title, content) {
+  const data = content;
+  writeFileSync(path.resolve(outputPath, 'pages', `${id}.adoc`), data);
 }
 
 function makeSidebar(program) {
+  const makeEntry = name => `* xref:${name}.adoc[${name}]`;
   const commands = program.commands
     // TODO: remove filtering status command before next major release
     .filter(command => command.name() !== 'status')
-    .map(command => `cli_${command.name()}`);
-  return {
-    'cli-api': {
-      commands: ['cli_main', ...commands],
-    },
-  };
+    .map(command => makeEntry(command.name()));
+  return ['.CLI', makeEntry('main'), ...commands].join('\n');
 }
 
 function run() {
-  if (!existsSync(outputPath)) {
-    mkdirSync(outputPath);
-  }
+  ensureDirSync(outputPath);
+  ensureDirSync(path.join(outputPath, 'pages'));
 
-  const main = renderToStaticMarkup(React.createElement(Main, { program }));
-  writeMd('main', 'zos', main);
+  const main = render(program);
+  writeAdoc('main', 'zos', main);
 
   program.commands
     // TODO: remove filtering status command before next major release
     .filter(command => command.name() !== 'status')
     .forEach(command => {
-      const content = renderToStaticMarkup(React.createElement(Command, { command }));
-      writeMd(command.name(), command.name(), content);
+      const content = render(command);
+      writeAdoc(command.name(), command.name(), content);
     });
 
   const sidebar = makeSidebar(program);
-  writeFileSync(path.resolve(outputPath, 'sidebars.json'), JSON.stringify(sidebar, null, 2));
+  writeFileSync(path.resolve(outputPath, 'nav.adoc'), sidebar);
 }
 
 run();
-console.log(`Docs generated in ${process.cwd()}/${outputPath}`);
+console.log(`Docs generated in ${path.resolve(outputPath)}`);

packages/cli/package.json

@@ -123,8 +123,6 @@
     "@types/lodash": "^4.14.119",
     "@types/mocha": "^5.2.5",
     "@types/node": "^10.12.12",
-    "@types/react": "^16.8.2",
-    "@types/react-dom": "^16.8.0",
     "@typescript-eslint/eslint-plugin": "^1.9.0",
     "@typescript-eslint/parser": "^1.9.0",
     "chai": "^4.1.2",
@@ -147,8 +145,6 @@
     "mock-stdlib-unpublished": "file:./test/mocks/mock-stdlib-unpublished",
     "mock-stdlib-unsupported": "file:./test/mocks/mock-stdlib-unsupported",
     "prettier": "^1.17.1",
-    "react": "^16.3.2",
-    "react-dom": "^16.3.2",
     "sinon": "^6.1.4",
     "sinon-chai": "^3.2.0",
     "truffle": "^5.0.5",

packages/cli/tsconfig.docs.json

@@ -3,7 +3,6 @@
   "defaultSeverity": "warning",
   "compilerOptions": {
     "allowJs": true,
-    "jsx": "react"
   },
   "include": [
     "./src"

packages/docs/.gitignore

@@ -1,3 +1,7 @@
 node_modules/
+openzeppelin-docs/
 docs/node_modules
 docs/website/build
+
+modules/lib
+modules/cli

packages/docs/antora.yml

@@ -0,0 +1,7 @@
+name: 'sdk'
+title: 'SDK'
+version: '2.4'
+nav: 
+  - modules/ROOT/nav.adoc
+  - modules/cli/nav.adoc
+  - modules/lib/nav.adoc