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

youknowriad · 2017-07-07T15:34:06Z

Requirements we're trying to achieve here:

A unique documentation tool for all our docs
Contains the creating blocks guide
Code examples are written in ES5 and ESnext.
Has to live in the repository
Integrate Well with the WordPress.org docs
Will contain the pattern library
- Loads and runs React Components
- Can change components' props live
Will be searchable
Can support advanced documentation (for example Redux's selectors discovery)

This PR adds a Docs tool called docutron you can launch like that:

npm run docs-start

The docs folder has an index.js as an Entry point where you can add "stories" to your documentation website:

import { addStory } from 'glutenberg';
import myReadme from '../readme.md';
addStory( {
  name: 'intro',
  title: 'Introduction',
  markdown: myReadme,
} );

For more flexibility, a story can provide a React Component instead of providing a markdown string.

nylen · 2017-07-07T15:41:35Z

Integrate Well with the WordPress.org docs

This is not something to solve today. However, what is the current plan for uploading this documentation to developer.wordpress.org? How do you see this integration going?

When we do that, let's clean up code samples on that site. Right now the font size is so big that they are almost impossible to usefully read.

youknowriad · 2017-07-07T15:58:41Z

This is not something to solve today. However, what is the current plan for uploading this documentation to developer.wordpress.org? How do you see this integration going?

Today, we're trying to just have a similar styling, and maybe we just embed an iframe in the WordPress docs since it's have the same styling.

coveralls · 2017-07-08T13:10:10Z

Changes Unknown when pulling f9e8caa on try/new-docs-tool into ** on master**.

coveralls · 2017-07-08T13:33:09Z

Changes Unknown when pulling 01d229c on try/new-docs-tool into ** on master**.

youknowriad · 2017-07-08T13:35:53Z

The documentation tool is almost ready. I need some eyes here cc @aduth
I wonder if we should merge this without completing the blocks guide.
Also, once merged, we'll have to PR and remove Storybook and update the deployment hook to deploy this instead.

coveralls · 2017-07-08T13:41:51Z

Changes Unknown when pulling debed01 on try/new-docs-tool into ** on master**.

aduth · 2017-07-08T13:39:11Z

docs-tool/src/components/Page.js

+
+		return (
+			<div>
+				<div>


Do we need the nested div ?

aduth · 2017-07-08T13:40:29Z

docs-tool/src/components/Page.js

+	}
+
+	componentDidUpdate() {
+		Prism.highlightAll();


Can we be more targeted about this? Either passing the individual node or the code content?

Going to leave this for now, because we technically don't know if there's a code content in the current tabs, these tabs can contain any markup.

aduth · 2017-07-08T13:41:24Z

docs-tool/src/components/Page.js

+
+class Page extends Component {
+	componentDidMount() {
+		Prism.highlightAll();


Seems odd to call code highlighting here, and not in the tabs.

This is necessary when you switch pages that contain code blocks without tabs

aduth · 2017-07-08T13:41:43Z

docs-tool/src/components/Page.js

+				<div className="navigation">
+					{ !! previousStory && (
+						<p className="nav-older">
+							<Link to={ previousStory.path }>{ '←' } { previousStory.title }</Link>


Does ← need to be wrapped as an expression?

The core docs include some extra hints here, like rel="previous" and rel="next".

https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types

The wrapping makes it more visible in my IDE. The same sign is used to display "tabs". But I can live without it if necessary

aduth · 2017-07-08T13:43:02Z

docs-tool/.gitignore

@@ -0,0 +1,21 @@
+# See https://help.github.com/ignore-files/ for more about ignoring files.


Should docs-tool be a top-level folder, or could we move it within docs?

I think we should move it outside the repository later, glutenberg maybe :)

aduth · 2017-07-08T13:46:09Z

docs-tool/bin/helpers/extend-webpack-config.js

+
+	// Adding the markdown loader and exclude if from the file loader
+	webpackConfig.module.rules.forEach( rule => {
+		if ( rule.loader === require.resolve( 'file-loader' ) ) {


Should loaders be defined in docs-tool/package.json if we're treating it as a separate project, or are these guaranteed to exist by create-react-app?

I think CRA guarantee this since it's using it.

aduth · 2017-07-08T13:47:19Z

docs-tool/src/components/Page.js

+	constructor() {
+		super( ...arguments );
+		this.state = {
+			activeTab: 0,


A future / present feature which would be nice to support is remembering preference across each page.

The problem here is that the tabs can be anything not always (es5, es6)

aduth · 2017-07-08T13:51:43Z

docs-tool/src/components/Sidebar.js

+	return (
+		<div id="secondary" className="widget-area">
+			<div className="secondary-content">
+				<aside id="handbook_pages-3" className="widget widget_wporg_handbook_pages">


Think we can drop the id.

aduth · 2017-07-08T13:52:42Z

docs-tool/src/index.js

@@ -0,0 +1,13 @@
+import React from 'react';
+import ReactDOM from 'react-dom';
+import 'prismjs';


Can we see if we can get rid of this? Not sure why we need both this and Prism.highlightAll(). Shouldn't highlightAll only be occurring when the code has been rendered anyways?

aduth · 2017-07-08T13:55:17Z

docs/stories/index.js

@@ -0,0 +1,47 @@
+import { addStory } from 'glutenberg';


Will we have more than one file in this folder? Should we start as docs/stories.js to avoid prematurely nesting directories?

coveralls · 2017-07-08T14:28:17Z

Changes Unknown when pulling 830c99a on try/new-docs-tool into ** on master**.

coveralls · 2017-07-08T14:31:33Z

Changes Unknown when pulling 830c99a on try/new-docs-tool into ** on master**.

coveralls · 2017-07-10T08:34:06Z

Changes Unknown when pulling 2455a663199eaa446c71381609ffeed40a9aaf7d on try/new-docs-tool into ** on master**.

coveralls · 2017-07-10T08:55:51Z

Coverage remained the same at 17.816% when pulling 1295aa972412f099381bce616920c867a77529c2 on try/new-docs-tool into d157b5e on master.

coveralls · 2017-07-10T09:05:11Z

Coverage remained the same at 17.816% when pulling 1295aa972412f099381bce616920c867a77529c2 on try/new-docs-tool into d157b5e on master.

coveralls · 2017-07-10T11:13:21Z

Coverage remained the same at 17.816% when pulling 0748c49843d05fff3e7cd1437de974388e0b018a on try/new-docs-tool into d157b5e on master.

coveralls · 2017-07-10T11:46:50Z

Coverage remained the same at 17.816% when pulling 2adf01f5153b18887648adb71c6e49ca3a5ea46e on try/new-docs-tool into d157b5e on master.

coveralls · 2017-07-10T11:54:14Z

Coverage remained the same at 17.816% when pulling 4a4a749569b47c1d69be8e3cf17d194e24f6a3cb on try/new-docs-tool into d157b5e on master.

aduth · 2017-07-10T16:33:58Z

docutron/bin/helpers/extend-webpack-config.js

+const path = require( 'path' );
+
+module.exports = function( webpackConfig, usersCwd ) {
+	const docsFolder = 'docs';


Should this be hard-coded as docs, or should we support specifying this from the command-line?

aduth · 2017-07-10T16:34:23Z

docutron/bin/cli.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+const path = require( 'path' );


Should we add DocBlocks for dependencies ("External dependencies", etc)? For consistency with other "modules".

aduth · 2017-07-10T16:38:26Z

docutron/src/components/Page.js

+import React, { Component } from 'react';
+import { Link } from 'react-router-dom';
+
+import { getNextStory, getPreviousStory } from 'docutron';


It seems a bit odd for this module to depend from itself. Should we instead import by traversing to the relative path?

aduth · 2017-07-10T16:38:45Z

docutron/src/components/Page.js

+import markdown from '../markdown';
+import Tabs from './Tabs';
+
+function MarkdownContent( { content } ) {


We might consider extracting this component to a separate file.

aduth · 2017-07-10T16:39:32Z

docutron/src/index.js

@@ -0,0 +1,12 @@
+import React from 'react'; // eslint-disable-line no-unused-vars


We shouldn't need eslint-disable-line no-unused-vars anymore.

🤖 Recalibrating mainframe...

Regression from rename

May be "nice to have", but not intending to support or maintain

Consistency with named file

Filter results updated live

aduth

This appears to be in a good state for an initial pass at documentation. Let's get this in and continue iterating.

karmatosed · 2017-07-17T19:21:56Z

Just checking on this, we have 2 issues for the pattern library here: https://github.com/WordPress/gutenberg/labels/Pattern%20Library. Is the idea that this works as that? I am trying to get context and don't want to duplicate if this is already happening.

aduth · 2017-07-18T19:49:40Z

@karmatosed I think the work here relates to the pattern library, but doesn't necessary supersede it. Rather, this merely sets a base for consolidating documentation, which we can build out to include a components library similar to Calypso DevDocs, homegrown in the same fashion. The problem with Storybook is that it worked particularly well at this one role of component demonstrations, but wouldn't allow us to scale up to include more forms of documentation, or style in a fashion that would be easy to integrate with the WordPress developer site.

karmatosed · 2017-07-18T20:21:06Z

@aduth thank you for explaining a little. I am really interested in anything that makes things easier :) How can we unite the approaches? I really would like to do that. Maybe we can take it to those tickets though, if that is more suitable?

aduth · 2017-07-18T20:43:04Z

Yes, let's move discussion into issues. I've left another comment at #1706 (comment)

…_bridge_and_aztec Hardcode Android RN version in bridge and aztec

youknowriad added the [Type] Developer Documentation Documentation for developers label Jul 7, 2017

youknowriad self-assigned this Jul 7, 2017

youknowriad requested a review from aduth July 7, 2017 15:34

youknowriad force-pushed the try/new-docs-tool branch 2 times, most recently from 86ac163 to 57bc239 Compare July 7, 2017 15:57

nylen mentioned this pull request Jul 7, 2017

Reformat and correct blocks/README.md #1794

Merged

youknowriad mentioned this pull request Jul 8, 2017

Add Dashicon component into Storybook #1776

Closed

youknowriad changed the title ~~[WIP] Documentation: Try a new custom documentation tool to rule them all~~ Documentation: Try a new custom documentation tool to rule them all Jul 8, 2017

aduth reviewed Jul 8, 2017

View reviewed changes

mtias mentioned this pull request Jul 8, 2017

Document all Block API functions #468

Closed

youknowriad force-pushed the try/new-docs-tool branch 2 times, most recently from 944bfed to 1295aa9 Compare July 10, 2017 08:51

youknowriad added 4 commits July 10, 2017 13:59

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

84631f8

Documentation: Adding Previous/Next Page links

92b72c9

Documentation: Parsing markdown blocks (code blocks)

4079c80

Documentation: Fix the doc tool title and metadata

05ffe5d

Documentation: Support overriding the default docs folder

740e21e

aduth reviewed Jul 10, 2017

View reviewed changes

youknowriad and others added 13 commits July 10, 2017 18:48

Documentation: Using the External/Internal dependencies comments

e0d7aa1

Fix references to accompanying examples plugin

ad149a6

Specify Docutron version

1305eec

🤖 Recalibrating mainframe...

Documentation: Drop eslint-disable-comment

f8f4a76

Use GitHub Pages for publishing documentation

6852f23

Extract components to separate files

3346367

Rename components as lowercase

5845a09

Fix typo in stylesheet ESNext example

794ba47

Fix import reference to app component

47ceaa2

Regression from rename

Apply rel on navigation links

891e90b

Remove service worker registration

62f769e

May be "nice to have", but not intending to support or maintain

Rename extendsConfig to extendConfig

d6e18e3

Consistency with named file

Prevent search form submission

38d0c0e

Filter results updated live

aduth approved these changes Jul 10, 2017

View reviewed changes

youknowriad merged commit 7779f79 into master Jul 10, 2017

youknowriad deleted the try/new-docs-tool branch July 10, 2017 17:33

This was referenced Jul 11, 2017

Document "query" capabilities #1491

Closed

Create documentation #1719

Closed

Create "Hello World" Block plugin examples with documentation #1619

Closed

aduth mentioned this pull request Jul 18, 2017

Format of the pattern library #1706

Closed

nylen mentioned this pull request Aug 1, 2017

Improve developer documentation for creating plugin blocks #2142

Closed

4 tasks

aduth mentioned this pull request Apr 3, 2018

Framework: Remove unused PrismJS dependency #5938

Merged

Tug pushed a commit that referenced this pull request Feb 28, 2020

Merge pull request #1786 from wordpress-mobile/harcode_RN_version_for…

2f87d55

…_bridge_and_aztec Hardcode Android RN version in bridge and aztec

draganescu mentioned this pull request Nov 7, 2023

Standardized way to modify interactive states (:hover, :focus .etc) for blocks #38277

Open

6 tasks

		@@ -0,0 +1,21 @@
		# See https://help.github.com/ignore-files/ for more about ignoring files.

		@@ -0,0 +1,14 @@
		#!/usr/bin/env node
		const path = require( 'path' );

		@@ -0,0 +1,12 @@
		import React from 'react'; // eslint-disable-line no-unused-vars

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

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

Conversation

youknowriad commented Jul 7, 2017 • edited Loading

nylen commented Jul 7, 2017

youknowriad commented Jul 7, 2017

coveralls commented Jul 8, 2017

coveralls commented Jul 8, 2017

youknowriad commented Jul 8, 2017

coveralls commented Jul 8, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

youknowriad Jul 8, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

coveralls commented Jul 8, 2017

coveralls commented Jul 8, 2017

coveralls commented Jul 10, 2017

coveralls commented Jul 10, 2017

coveralls commented Jul 10, 2017

coveralls commented Jul 10, 2017

coveralls commented Jul 10, 2017

coveralls commented Jul 10, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aduth left a comment

Choose a reason for hiding this comment

karmatosed commented Jul 17, 2017

aduth commented Jul 18, 2017

karmatosed commented Jul 18, 2017

aduth commented Jul 18, 2017

youknowriad commented Jul 7, 2017 •

edited

Loading

youknowriad Jul 8, 2017 •

edited

Loading