Documentation: Try a new custom documentation tool to rule them all

WordPress · Jul 7, 2017 · 57bc239 · 57bc239
1 parent 4dc462c
commit 57bc239
Show file tree

Hide file tree

Showing 20 changed files with 581 additions and 0 deletions.
diff --git a/docs-tool/.gitignore b/docs-tool/.gitignore
@@ -0,0 +1,21 @@
+# See https://help.github.com/ignore-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+
+# testing
+/coverage
+
+# production
+/build
+
+# misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
diff --git a/docs-tool/bin/build.js b/docs-tool/bin/build.js
@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+const path = require( 'path' );
+const extendsConfig = require( './helpers/extend-webpack-config' );
+const usersCwd = process.cwd();
+
+// webpack.config.prod.js checks this.
+process.env.NODE_ENV = 'production';
+
+// Load and edit the create-react-app config.
+process.chdir( path.resolve( __dirname, '../' ) );
+const webpackConfig = require( 'react-scripts/config/webpack.config.prod' );
+extendsConfig( webpackConfig, usersCwd );
+
+// Run the build.
+require( 'react-scripts/scripts/build' );
diff --git a/docs-tool/bin/helpers/extend-webpack-config.js b/docs-tool/bin/helpers/extend-webpack-config.js
@@ -0,0 +1,33 @@
+const path = require( 'path' );
+
+module.exports = function( webpackConfig, usersCwd ) {
+	// Adding "glutenberg" alias
+	webpackConfig.resolve.alias.glutenberg = path.resolve( __dirname, '../../src/config/' );
+
+	// Loading the config folder
+	webpackConfig.resolve.alias.config = path.resolve( usersCwd, process.argv[ 2 ] );
+	webpackConfig.resolve.modules = webpackConfig.resolve.modules.concat( [ webpackConfig.resolve.alias.config ] );
+
+	// Using the user's node_modules
+	const usersNodeModules = path.resolve( usersCwd, 'node_modules' );
+	webpackConfig.resolve.modules = webpackConfig.resolve.modules.concat( [ usersNodeModules ] );
+
+	// Deleting CRA scoping
+	webpackConfig.resolve.plugins = [];
+	webpackConfig.module.rules.forEach( ( rule ) => {
+		if ( rule.include ) {
+			rule.include = [ rule.include, webpackConfig.resolve.alias.config ];
+		}
+	} );
+
+	// Adding the markdown loader and exclude if from the file loader
+	webpackConfig.module.rules.forEach( rule => {
+		if ( rule.loader === require.resolve('file-loader') ) {
+			rule.exclude.push( /\.md/ );
+		}
+	} );
+	webpackConfig.module.rules.push( {
+		test: /\.md/,
+		use: require.resolve( 'raw-loader' ),
+	} );
+}
diff --git a/docs-tool/bin/start.js b/docs-tool/bin/start.js
@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+const path = require( 'path' );
+const extendsConfig = require( './helpers/extend-webpack-config' );
+const usersCwd = process.cwd();
+
+// webpack.config.prod.js checks this.
+process.env.NODE_ENV = 'development';
+
+// Load and edit the create-react-app config.
+process.chdir( path.resolve( __dirname, '../' ) );
+const webpackConfig = require( 'react-scripts/config/webpack.config.dev' );
+extendsConfig( webpackConfig, usersCwd );
+
+// Run the build.
+require( 'react-scripts/scripts/start' );
diff --git a/docs-tool/package.json b/docs-tool/package.json
@@ -0,0 +1,20 @@
+{
+  "name": "docs-tool",
+  "version": "0.1.0",
+  "private": true,
+  "dependencies": {
+    "prismjs": "^1.6.0",
+    "react": "^15.6.1",
+    "react-dom": "^15.6.1",
+    "react-markdown": "^2.5.0",
+    "react-router-dom": "^4.1.1",
+    "react-scripts": "1.0.10"
+  },
+  "scripts": {
+    "start": "react-scripts start",
+    "build": "react-scripts build",
+    "test": "react-scripts test --env=jsdom",
+    "eject": "react-scripts eject"
+  },
+  "devDependencies": {}
+}
diff --git a/docs-tool/public/favicon.ico b/docs-tool/public/favicon.ico
diff --git a/docs-tool/public/index.html b/docs-tool/public/index.html
@@ -0,0 +1,42 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+    <meta name="theme-color" content="#000000">
+    <!--
+      manifest.json provides metadata used when your web app is added to the
+      homescreen on Android. See https://developers.google.com/web/fundamentals/engage-and-retain/web-app-manifest/
+    -->
+    <link rel="manifest" href="%PUBLIC_URL%/manifest.json">
+    <link rel="shortcut icon" href="%PUBLIC_URL%/favicon.ico">
+		<link rel="stylesheet" type="text/css" href="https://make.wordpress.org/docs/wp-content/themes/p2-breathe/style.css">
+		<link rel="stylesheet" type="text/css" href="https://make.wordpress.org/docs/wp-content/themes/pub/wporg-breathe/style.css">
+    <!--
+      Notice the use of %PUBLIC_URL% in the tags above.
+      It will be replaced with the URL of the `public` folder during the build.
+      Only files inside the `public` folder can be referenced from the HTML.
+
+      Unlike "/favicon.ico" or "favicon.ico", "%PUBLIC_URL%/favicon.ico" will
+      work correctly both with client-side routing and a non-root public URL.
+      Learn how to configure a non-root public URL by running `npm run build`.
+    -->
+    <title>React App</title>
+  </head>
+  <body>
+    <noscript>
+      You need to enable JavaScript to run this app.
+    </noscript>
+    <div id="root"></div>
+    <!--
+      This HTML file is a template.
+      If you open it directly in the browser, you will see an empty page.
+
+      You can add webfonts, meta tags, or analytics to this file.
+      The build step will place the bundled scripts into the <body> tag.
+
+      To begin the development, run `npm start` or `yarn start`.
+      To create a production bundle, use `npm run build` or `yarn build`.
+    -->
+  </body>
+</html>
diff --git a/docs-tool/public/manifest.json b/docs-tool/public/manifest.json
@@ -0,0 +1,15 @@
+{
+  "short_name": "React App",
+  "name": "Create React App Sample",
+  "icons": [
+    {
+      "src": "favicon.ico",
+      "sizes": "192x192",
+      "type": "image/png"
+    }
+  ],
+  "start_url": "./index.html",
+  "display": "standalone",
+  "theme_color": "#000000",
+  "background_color": "#ffffff"
+}
diff --git a/docs-tool/src/App.js b/docs-tool/src/App.js
@@ -0,0 +1,37 @@
+import React, { Component } from 'react';
+import { BrowserRouter, Route } from 'react-router-dom';
+import Prism from 'prismjs';
+
+import { getStories } from 'glutenberg';
+import Sidebar from './Sidebar';
+
+const createPage = ( Comp ) => class extends Component {
+	componentDidMount( prevProps ) {
+		Prism.highlightAll();
+	}
+
+	render() {
+		return <Comp />;
+	}
+}
+
+const App = () => {
+  return (
+	  <BrowserRouter>
+			<div className="single-handbook">
+				<div id="page">
+			    <div id="main" className="site-main clear">
+						<Sidebar />
+						<div id="primary" className="content-area">
+							{ getStories().map( ( { path, Component: Comp }, index ) => (
+								<Route key={ index } path={ path } component={ createPage( Comp ) } exact />
+							) ) }
+						</div>
+			    </div>
+				</div>
+			</div>
+	  </BrowserRouter>
+  );
+}
+
+export default App;
diff --git a/docs-tool/src/Sidebar.js b/docs-tool/src/Sidebar.js
@@ -0,0 +1,46 @@
+import React from 'react';
+import { Link } from 'react-router-dom';
+
+import { getStoriesTree } from 'glutenberg';
+
+function MenuItem( { item } ) {
+	return (
+		<li>
+			{ ! item.children.length && <Link to={ item.path }>{ item.title }</Link> }
+			{ !! item.children.length && (
+				<div className="expandable">
+					<span className="dashicons dashicons-arrow-down-alt2"></span>
+					<Link to={ item.path }>{ item.title }</Link>
+				</div>
+			) }
+			{ !! item.children.length && (
+				<ul>
+					{ item.children.map( ( story, index) => (
+						<MenuItem key={ index } item={ story } />
+					) ) }
+				</ul>
+			) }
+		</li>
+	);
+}
+
+function Sidebar() {
+	return (
+		<div id="secondary" className="widget-area">
+			<div className="secondary-content">
+				<aside id="handbook_pages-3" className="widget widget_wporg_handbook_pages">
+					<h2 className="widget-title">Documentation</h2>
+					<div className="menu-table-of-contents-container">
+						<ul>
+							{ getStoriesTree().map( ( story, index ) => (
+								<MenuItem key={ index } item={ story } />
+							) ) }
+						</ul>
+					</div>
+				</aside>
+			</div>
+		</div>
+	);
+}
+
+export default Sidebar;
diff --git a/docs-tool/src/config/index.js b/docs-tool/src/config/index.js
@@ -0,0 +1,36 @@
+import React from 'react';
+import ReactMarkdown from 'react-markdown';
+
+const stories = [];
+
+export function addStory( story ) {
+	const { name, parents = [], markdown } = story;
+	stories.push( {
+		path: '/' + parents.concat( name ).join( '/' ),
+		id: parents.concat( name ).join( '.' ),
+		parent: parents.join( '.' ),
+		Component: markdown ? () => <ReactMarkdown source={ markdown } /> : story.Component,
+		...story,
+	} );
+}
+
+export function getStories() {
+	return stories;
+}
+
+export function getStoriesTree() {
+	const buildTreeNode = ( story ) => {
+		return  {
+			...story,
+			children: buildTreeChildren( story.id ),
+		};
+	}
+
+	const buildTreeChildren = ( parentId = '' ) => {
+		return stories
+			.filter( ( story ) => story.parent === parentId )
+			.map( buildTreeNode );
+	};
+
+	return buildTreeChildren();
+}
diff --git a/docs-tool/src/index.js b/docs-tool/src/index.js
@@ -0,0 +1,13 @@
+import React from 'react';
+import ReactDOM from 'react-dom';
+import 'prismjs';
+import 'prismjs/themes/prism.css';
+
+import 'config';
+
+import App from './App';
+import registerServiceWorker from './registerServiceWorker';
+import './styles/main.css';
+
+ReactDOM.render(<App />, document.getElementById('root'));
+registerServiceWorker();