From b7a7a22397121b41770a9dacbd5c50db11251b37 Mon Sep 17 00:00:00 2001 From: Greg Thompson Date: Wed, 9 Jan 2019 14:06:30 -0600 Subject: [PATCH] Fix broken docs links (#1416) * convert EuiLink instances with intenal routing to react-router Link * convert react-router Link instances with external routing to EuiLink * convert faux links to use hash * Start to documentation guidelines: internal and external links * reinstate local relative url * update external link doc guidlines --- src-docs/src/views/badge/badge_example.js | 13 ++++--- src-docs/src/views/button/button_example.js | 7 +++- .../form_controls/form_controls_example.js | 9 +++-- src-docs/src/views/guidelines/colors.js | 7 +++- src-docs/src/views/guidelines/sass.js | 8 ++-- src-docs/src/views/home/home_view.js | 8 +++- .../src/views/list_group/list_group_links.js | 10 ++--- src-docs/src/views/toggle/toggle_example.js | 13 ++++--- wiki/documentation-guidelines.md | 38 +++++++++++++++++++ 9 files changed, 86 insertions(+), 27 deletions(-) create mode 100644 wiki/documentation-guidelines.md diff --git a/src-docs/src/views/badge/badge_example.js b/src-docs/src/views/badge/badge_example.js index 7bba9f2f9bc..64a3ae1a1ce 100644 --- a/src-docs/src/views/badge/badge_example.js +++ b/src-docs/src/views/badge/badge_example.js @@ -1,5 +1,9 @@ import React from 'react'; +import { + Link, +} from 'react-router'; + import { renderToHtml } from '../../services'; import { @@ -10,7 +14,6 @@ import { EuiBadge, EuiCode, EuiBetaBadge, - EuiLink, EuiNotificationBadge, } from '../../../../src/components'; @@ -111,8 +114,8 @@ export const BadgeExample = { components like the EuiKeyPadMenuItem.

- They can also be used in conjunction with EuiCards -  and EuiKeyPadMenuItems. + They can also be used in conjunction with EuiCards +  and EuiKeyPadMenuItems.

), @@ -130,8 +133,8 @@ export const BadgeExample = { text: (

Used to showcase the number of notifications, alerts or hidden selections. - Typically used in EuiHeader or - (eventually) EuiFilterButtons. + Typically used in EuiHeader or + (eventually) EuiFilterButtons.

), props: { EuiNotificationBadge }, diff --git a/src-docs/src/views/button/button_example.js b/src-docs/src/views/button/button_example.js index 8f5f3d8b4a0..c2d5f78374d 100644 --- a/src-docs/src/views/button/button_example.js +++ b/src-docs/src/views/button/button_example.js @@ -1,5 +1,9 @@ import React from 'react'; +import { + Link, +} from 'react-router'; + import { renderToHtml } from '../../services'; import { GuideSectionTypes } from '../../components'; @@ -11,7 +15,6 @@ import { EuiCode, EuiButtonGroup, EuiButtonToggle, - EuiLink, } from '../../../../src/components'; import Button from './button'; @@ -271,7 +274,7 @@ export const ButtonExample = { color='ghost' to any of the button styles on this page. These should be used extremely rarely, and are only for placing buttons on top of dark or image-based backgrounds. A good example of their use is in the{' '} - EuiBottomBar component. + EuiBottomBar component.

), demo: , diff --git a/src-docs/src/views/form_controls/form_controls_example.js b/src-docs/src/views/form_controls/form_controls_example.js index cf3d4f0115a..7cf3be3554e 100644 --- a/src-docs/src/views/form_controls/form_controls_example.js +++ b/src-docs/src/views/form_controls/form_controls_example.js @@ -1,5 +1,9 @@ import React, { Fragment } from 'react'; +import { + Link, +} from 'react-router'; + import { renderToHtml } from '../../services'; import { @@ -185,8 +189,8 @@ export const FormControlsExample = { text: (

This component renders a basic HTML <select> element. If you need more customization - for how the options and/or selected values render, use the EuiSuperSelect. - Another option is to use the EuiComboBox, which has search and multi-select + for how the options and/or selected values render, use the EuiSuperSelect. + Another option is to use the EuiComboBox, which has search and multi-select capabilities, but also has restrictions on how items are rendered.

), @@ -328,4 +332,3 @@ export const FormControlsExample = { demo: , }], }; - diff --git a/src-docs/src/views/guidelines/colors.js b/src-docs/src/views/guidelines/colors.js index 653d56a8bf5..3b460a2c648 100644 --- a/src-docs/src/views/guidelines/colors.js +++ b/src-docs/src/views/guidelines/colors.js @@ -1,4 +1,9 @@ import React, { Component } from 'react'; + +import { + Link, +} from 'react-router'; + import lightColors from '!!sass-vars-to-js-loader!../../../../src/global_styling/variables/_colors.scss'; import { calculateContrast, rgbToHex } from '../../../../src/services'; @@ -300,7 +305,7 @@ color: $${color2};`

For more visualization palettes and rendering services, go to - the Color Palettes utility page. + the Color Palettes utility page.

diff --git a/src-docs/src/views/guidelines/sass.js b/src-docs/src/views/guidelines/sass.js index 683c79df20f..31ace098e93 100644 --- a/src-docs/src/views/guidelines/sass.js +++ b/src-docs/src/views/guidelines/sass.js @@ -308,8 +308,8 @@ const importOutsideExample = (`// In an outside project, import the core variabl `); const tintOrShadeExample = (`// tintOrShade(color, tint_percent, shade_percent) -// will tint the color by % in light themes -// and shade the color by % in dark themes +// will tint the color by % in light themes +// and shade the color by % in dark themes .themedBox { background-color: tintOrShade($euiColorPrimary, 90%, 70%); border-left: $euiBorderThick; @@ -749,7 +749,7 @@ export default() => (

- View the sass code for media queries. + View the sass code for media queries.

Breakpoints in EUI are provided through the use of a sass @@ -821,7 +821,7 @@ export default() => ( Animation

- View the sass code for animation. + View the sass code for animation.

EUI utilizes the following constants to maintain a similar 'bounce' to its animations. diff --git a/src-docs/src/views/home/home_view.js b/src-docs/src/views/home/home_view.js index d4dbd0cc6cf..00825810924 100644 --- a/src-docs/src/views/home/home_view.js +++ b/src-docs/src/views/home/home_view.js @@ -1,5 +1,9 @@ import React from 'react'; +import { + Link, +} from 'react-router'; + import imageIcons from '../../images/icons.jpg'; import imageButtons from '../../images/buttons.svg'; import imageTables from '../../images/tables.svg'; @@ -36,9 +40,9 @@ export const HomeView = () => (

Version:{' '} - + v{ pkg.version } - +

diff --git a/src-docs/src/views/list_group/list_group_links.js b/src-docs/src/views/list_group/list_group_links.js index 19ce6c909c8..0f9d4268ecc 100644 --- a/src-docs/src/views/list_group/list_group_links.js +++ b/src-docs/src/views/list_group/list_group_links.js @@ -12,33 +12,33 @@ import { const myContent = [ { label: 'First link', - href: '/#/display/list-group', + href: '#/display/list-group', iconType: 'calendar', size: 's', }, { label: 'Second link is active', - href: '/#/display/list-group', + href: '#/display/list-group', isActive: true, iconType: 'clock', size: 's', }, { label: 'Third link is disabled', - href: '/#/display/list-group', + href: '#/display/list-group', isDisabled: true, iconType: 'compute', size: 's', }, { label: 'Fourth link', - href: '/#/display/list-group', + href: '#/display/list-group', iconType: 'copyClipboard', size: 's', }, { label: 'Fifth link', - href: '/#/display/list-group', + href: '#/display/list-group', iconType: 'crosshairs', size: 's', }, diff --git a/src-docs/src/views/toggle/toggle_example.js b/src-docs/src/views/toggle/toggle_example.js index 1b505ba4e36..d8cdbbcafe4 100644 --- a/src-docs/src/views/toggle/toggle_example.js +++ b/src-docs/src/views/toggle/toggle_example.js @@ -1,5 +1,9 @@ import React from 'react'; +import { + Link, +} from 'react-router'; + import { renderToHtml } from '../../services'; import { @@ -9,7 +13,6 @@ import { import { EuiCode, EuiToggle, - EuiLink, EuiCallOut, } from '../../../../src/components'; @@ -35,16 +38,16 @@ export const ToggleExample = { a visibly hidden input (checkbox or radio) overtop of the children provided.

- By default, the children will be wrapped in a block element. To change the display you can - simply use one of the utility classes - like .eui-displayInlineBlock. + By default, the children will be wrapped in a block element. + To change the display you can simply use one of + the utility classes like .eui-displayInlineBlock.

This utility is just a helper component and comes with no inherit styles including no :hover or :focus states. If you use this utility directly, be sure to add these states. Otherwise, you may just want to utilize - the EuiButtonToggle component. + the EuiButtonToggle component.

diff --git a/wiki/documentation-guidelines.md b/wiki/documentation-guidelines.md new file mode 100644 index 00000000000..2a7638e2049 --- /dev/null +++ b/wiki/documentation-guidelines.md @@ -0,0 +1,38 @@ +# Documentation guidelines + +## Links + +### Linking between EUI doc pages/components + +In instances where you would like to provide a link to another EUI component +referenced in a given component description or example, take advantage of `react-router`, +which is used for routing in EUI docs. Aside from the benefit of shorter path names, `react-router` will take the environment into account and provide the correct URL for both development and production locations. + +#### Basic example: + +```js +import { + Link, +} from 'react-router'; + +// ... + +Consult the larger color guidelines page +for a better explanation about passing color contrast. +``` + +### Linking to external resources + +When referring to external sites or resources, use EUI components that take an `href` prop, such as `EuiLink`. + +#### Basic example: + +```js +import { + EuiLink, +} from '/src/components'; + +// ... + +View the Sass code for shadow mixins. +```