docs: add documentation storybook for consumers #526

rshen91 · 2020-01-24T18:46:22Z

Summary

This PR is addressing issue #523.
This documentation specific storybook can be run using yarn start-docs. The files for this storybook are in the /docs and .storybook-docs directories.

Just to keep in mind, the files in /docs are prefixed with numbers for consistent ordering. You can change the folder structure by changing the Meta title="" prop within each .mdx file.

For instance the pie chart currently has the Meta title prop set to <Meta title="Types of charts/Sunburts/Basic pie chart" />.

There is a charts.tsx file within /docs to copy over components from the /stories directory and import chart dependencies there vs. impacting the visual regression tests by importing through /stories directly. For the most part, the chart.tsx file isn't itself rendering documentation (expect these lines are important:

export default {
  title: 'Introduction',
  includeStories: [],
};

), the files that are doing so are the .mdx files within /docs.

Some tasks to be completed in this PR:

Set up yarn start-docs command to run separate storybook
Set up MDX formatting for stories
Set up props tables
Set up story sources that are accurate

Checklist

Use ~~strikethroughs~~ to remove checklist items you don't feel are applicable to this PR.

~~- [] Any consumer-facing exports were added to src/index.ts (and stories only import from ../src except for test data & storybook)~~

This was checked for cross-browser compatibility, including a check against IE11
Proper documentation or storybook story was added for features that require explanation or tutorials
~~- [ ] Unit tests were updated or added to match the most common scenarios~~
Each commit follows the convention

markov00

The overall structure looks good to me.
Before hosting the new docs, we need to clean, review and update them.
One major comment: we should try to avoid copy and paste of code and tables, instead we should prefer the mdx transclusion see https://mdxjs.com/getting-started#documents to import other mdx files inside a single mdx one (see storybookjs/storybook#7644 for issues with importing .md or .mdx)

markov00 · 2020-02-11T10:56:13Z

docs/0-Intro/0-Intro.mdx

+You can import Chart components from the top-level Elastic Chart module.
+
+```js
+import { Axis, BarSeries, Chart, getAxisId, getSpecId, Position, ScaleType } from '@elastic/charts';


We can remove the getAxisId and getSpecId, and reorder this by usage like

Suggested change

import { Axis, BarSeries, Chart, getAxisId, getSpecId, Position, ScaleType } from '@elastic/charts';

import { Chart, BarSeries, ScaleType, Axis, Position } from '@elastic/charts';

Because we first add the Chart, then a BarSeries and the scaleType, then we add an axis and its position

Addressed in 5ae0913

markov00 · 2020-02-11T10:56:41Z

docs/0-Intro/0-Intro.mdx

+## Consuming Elastic Charts
+
+
+### Components


we can remove this title

Addressed in 5ae0913

markov00 · 2020-02-11T10:58:10Z

docs/0-Intro/1-Overview.mdx

@@ -0,0 +1,257 @@
+import { Meta, Story } from "@storybook/addon-docs/blocks";


This overview is a bit outdated, let's for the moment leave it like that, I will review it later

markov00 · 2020-02-11T10:59:25Z

docs/1-Typesofchart/0-Bar.mdx

+
+<Chart className={'story-chart'}>
+    <BarSeries
+    id={getSpecId('bars1')}


we need to remove all getSpecsId/getAxisId etc because we don't need to use them anymore

addressed in 5ae0913

markov00 · 2020-02-11T11:01:18Z

docs/1-Typesofchart/0-Bar.mdx

+
+
+## Code for the basic bar chart 
+<details>


we can add the summary here and remove the title ## Code for the basic bar chart

with

<details> <summary> Code </summary> ...

Addressed in commit 5ae0913

markov00 · 2020-02-11T11:07:41Z

docs/1-Typesofchart/0-Bar.mdx

+</details>
+
+***
+## Prop Table for the basic bar chart


This comments can be applied to all the props table: the Props table refers to the BarSeries component not to the bar chart in general.
Few things that we can try/fix here:

from the title should be clear enough that we are referring to the BarSeries component Prop table, something like :BarSeries component Props table or <BarSeries /> props table should be used

I think we can use mdx transclusion to import an mdx file from somewhere else. It will be great if we can have a single file for each prop table and import just the table, so we don't have to copy/paste everything the same code

Addressed in 5ae0913

markov00 · 2020-02-11T11:08:09Z

docs/1-Typesofchart/0-Bar.mdx

+
+| Prop | Type | Default | Note |
+|:------|:------:|:---------:|:------|
+| id  `(required)` | `AxisId or string` |  | The id of the spec |


I will review all the tables, but just to mention that this should not be an AxisId

I think I caught them all! Addressed in 5ae0913

markov00 · 2020-02-11T11:09:08Z

docs/1-Typesofchart/0-Bar.mdx

+
+# Bar Chart with Axes 
+
+This chart now includes x and y axes. These axes can be `linear`, `ordinal` or `time`. 


If we want to introduce the axes here, we should also introduce the Axis Props table

Right on - added in 5ae0913

markov00 · 2020-02-11T11:11:26Z

src/chart_types/xy_chart/specs/area_series.tsx

@@ -9,7 +9,7 @@ const defaultProps = {
  specType: SpecTypes.Series,
  seriesType: SeriesTypes.Area,
  groupId: DEFAULT_GLOBAL_ID,
-  xScaleType: ScaleType.Ordinal,


Nice find 👍

codecov-io · 2020-02-11T19:34:33Z

Codecov Report

Merging #526 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #526   +/-   ##
=======================================
  Coverage   75.88%   75.88%           
=======================================
  Files         194      194           
  Lines        5879     5879           
  Branches     1143     1143           
=======================================
  Hits         4461     4461           
  Misses       1401     1401           
  Partials       17       17

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 510f58f...5ae0913. Read the comment docs.

markov00 · 2020-02-12T18:46:15Z

🎉 This PR is included in version 17.1.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

markov00 · 2020-02-21T05:15:40Z

🎉 This PR is included in version 17.1.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

rshen91 added 2 commits January 24, 2020 11:44

feat: set up yarn start-docs

f1b6630

feat: add babel config for mdx WIP

e472348

rshen91 changed the title ~~feat: add documentation storybook for consumers~~ docs: add documentation storybook for consumers Jan 27, 2020

rshen91 added 2 commits January 30, 2020 10:50

feat: working mdx format

2d69da4

fix: add withAxis and styling

98fc140

rshen91 force-pushed the doc-storybook branch from 2353492 to 98fc140 Compare January 30, 2020 18:17

rshen91 added 16 commits January 30, 2020 11:18

Merge remote-tracking branch 'upstream/master' into doc-storybook

ee45421

feat: improve docs for withaxis and basic

6d18f68

Merge remote-tracking branch 'upstream/master' into doc-storybook

f7f1ff5

WIP

926f0f6

WIP

09598df

fix: add yarn.lock file to resolve test failures

c3a2b0b

feat: add better organization for fs

2890797

feat: adding content to legend and annotation content

0c8ca2b

fix: remove export from annotation stories

0a2bb51

feat: add stacked stories and add content

8de9bcb

Merge remote-tracking branch 'upstream/master' into doc-storybook

33cb41a

WIP

277dddd

Merge remote-tracking branch 'upstream/master' into doc-storybook

901dee1

style: add syntax highlighting to code blocks

eb1613b

style: add collapsable code snippets

4dd512b

feat: add content to intro, props and code snippets

a11776f

rshen91 marked this pull request as ready for review February 6, 2020 23:12

rshen91 requested a review from markov00 February 6, 2020 23:12

rshen91 added 3 commits February 7, 2020 09:05

feat: edit prop tables and add content

49b241b

Merge remote-tracking branch 'upstream/master' into doc-storybook

510f58f

Merge remote-tracking branch 'upstream/master' into doc-storybook

693d631

elastic deleted a comment from robgil Feb 11, 2020

elastic deleted a comment from codecov-io Feb 11, 2020

elastic deleted a comment from robgil Feb 11, 2020

elastic deleted a comment from codecov-io Feb 11, 2020

elastic deleted a comment from robgil Feb 11, 2020

elastic deleted a comment from codecov-io Feb 11, 2020

markov00 approved these changes Feb 11, 2020

View reviewed changes

feat: separate prop tables and remove getSpecId getAxisId

5ae0913

rshen91 merged commit 75ff2ad into elastic:master Feb 11, 2020

rshen91 deleted the doc-storybook branch February 11, 2020 20:42

markov00 added the released Issue released publicly label Feb 12, 2020

markov00 added the released on @17.1.x label Feb 21, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add documentation storybook for consumers #526

docs: add documentation storybook for consumers #526

rshen91 commented Jan 24, 2020 •

edited

Loading

markov00 left a comment

markov00 Feb 11, 2020

rshen91 Feb 11, 2020

markov00 Feb 11, 2020

rshen91 Feb 11, 2020

markov00 Feb 11, 2020

markov00 Feb 11, 2020

rshen91 Feb 11, 2020

markov00 Feb 11, 2020

rshen91 Feb 11, 2020

markov00 Feb 11, 2020

rshen91 Feb 11, 2020

markov00 Feb 11, 2020

rshen91 Feb 11, 2020

markov00 Feb 11, 2020

rshen91 Feb 11, 2020

markov00 Feb 11, 2020

codecov-io commented Feb 11, 2020 •

edited

Loading

markov00 commented Feb 12, 2020

markov00 commented Feb 21, 2020

	import { Axis, BarSeries, Chart, getAxisId, getSpecId, Position, ScaleType } from '@elastic/charts';
	import { Chart, BarSeries, ScaleType, Axis, Position } from '@elastic/charts';

		@@ -0,0 +1,257 @@
		import { Meta, Story } from "@storybook/addon-docs/blocks";


		# Bar Chart with Axes

		This chart now includes x and y axes. These axes can be `linear`, `ordinal` or `time`.

docs: add documentation storybook for consumers #526

docs: add documentation storybook for consumers #526

Conversation

rshen91 commented Jan 24, 2020 • edited Loading

Summary

Checklist

markov00 left a 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

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

codecov-io commented Feb 11, 2020 • edited Loading

Codecov Report

markov00 commented Feb 12, 2020

markov00 commented Feb 21, 2020

rshen91 commented Jan 24, 2020 •

edited

Loading

codecov-io commented Feb 11, 2020 •

edited

Loading