WIP: add glossary with some basic DVC terms

src/Documentation/Markdown/Markdown.js

@@ -2,6 +2,7 @@ import React, { Component } from 'react'
 // components
 import ReactMarkdown from 'react-markdown'
 import { LightButton } from '../LightButton'
+import Tooltip from '../../Tooltip'
 // syntax highlighter
 import SyntaxHighlighter, {
   registerLanguage
@@ -48,15 +49,18 @@ const HeadingRenderer = ({ level, children }) => {
 }
 
 const HtmlRenderer = props => {
-  if (props.tag !== 'details') {
+  if (props.tag !== 'details' && props.tag !== 'abbr') {
     return React.createElement(props.tag, {}, props.children)
-  } else {
+  } else if (props.tag === 'details') {
     const text = props.children[0].props.children[0]
     return (
       <Collapsible trigger={text} transitionTime={200}>
         {props.children.slice(1)}
       </Collapsible>
     )
+  } else if (props.tag === 'abbr') {
+    const text = props.children[0]
+    return <Tooltip text={text} />
   }
 }
 

src/Documentation/glossary.js

@@ -0,0 +1,34 @@
+export default {
+  name: 'Glossary',
+  desc:
+    'This guide is aimed to familiarize the users with definitions to ' +
+    'relevant DVC concepts and terminologies which are frequently used.',
+  contents: [
+    {
+      name: 'Workspace directory',
+      match: ['workspace'],
+      desc:
+        'The **workspace** contains all of your DVC **project** files and ' +
+        "directories. It's typically also a Git **repository**. See also " +
+        '[`dvc init`](/doc/commands-reference/init).'
+    },
+    {
+      name: 'DVC cache',
+      match: ['cache'],
+      desc:
+        'DVC cache is a hidden storage which is found at `.dvc/cache`. This ' +
+        'storage is used to manage different versions of files which are ' +
+        'under DVC control. For more information on cache, please refer to ' +
+        'the this [guide](/doc/commands-reference/config#cache).'
+    },
+    {
+      name: 'Data artifact',
+      match: ['data artifact', 'data artifacts'],
+      desc:
+        'Any **data** file or directory, as well as intermediate or final ' +
+        'result (such as extracted features or a ML model file) that is ' +
+        'under DVC control. Refer to [Data and Model Files Versioning]' +
+        '(/doc/use-cases/data-and-model-files-versioning) for more details.'
+    }
+  ]
+}

src/Tooltip/index.js

@@ -0,0 +1,228 @@
+import React, { Component } from 'react'
+import ReactMarkdown from 'react-markdown'
+import styled from 'styled-components'
+
+import glossary from '../Documentation/glossary'
+
+class Tooltip extends Component {
+  state = {
+    description: '',
+    header: '',
+    hover: false,
+    id: null,
+    margin: -70,
+    pointBorderAfter: 'white transparent transparent transparent',
+    pointBorderBefore: '#d1d5da transparent transparent transparent',
+    pointMargin: -15,
+    pointTop: 100,
+    pointTopAfter: -14,
+    pointTopBefore: 16,
+    timeout: null,
+    top: 'unset',
+    width: 400
+  }
+
+  componentDidMount() {
+    glossary.contents.forEach((glossaryItem, index) => {
+      if (glossaryItem.match.includes(this.props.text)) {
+        this.setState({
+          description: glossaryItem.desc,
+          header: glossaryItem.name,
+          key: index
+        })
+      }
+    })
+  }
+
+  tooltipPositionEval = () => {
+    const markdownBody = document.getElementsByClassName('markdown-body')[0]
+    const tooltipBoundary = document
+      .getElementById(`tooltip-text-${this.state.key}`)
+      .getBoundingClientRect()
+    const tooltipBoxHeight = document.getElementById(
+      `tooltip-box-${this.state.key}`
+    ).offsetHeight
+    const tooltipHeight = tooltipBoundary.top - tooltipBoxHeight
+    const maxWidth = markdownBody.offsetLeft + markdownBody.clientWidth
+    const container = document.getElementsByClassName('tooltip-container')[0]
+    const tooltipWidth = container.offsetLeft + this.state.width
+    const vertical = tooltipHeight > 80 ? 'top' : 'bottom'
+    const horizontal = tooltipWidth > maxWidth ? 'right' : 'left'
+
+    switch (`${horizontal} ${vertical}`) {
+      case 'left top':
+        this.setState({
+          margin: -70,
+          pointBorderAfter: 'white transparent transparent transparent',
+          pointBorderBefore: '#d1d5da transparent transparent transparent',
+          pointMargin: -15,
+          pointTop: 100,
+          pointTopAfter: 'unset',
+          pointTopBefore: 'unset',
+          top: -tooltipBoxHeight
+        })
+        break
+      case 'right top':
+        this.setState({
+          margin: -340,
+          pointBorderAfter: 'white transparent transparent transparent',
+          pointBorderBefore: '#d1d5da transparent transparent transparent',
+          pointMargin: 260,
+          pointTop: 100,
+          pointTopAfter: 'unset',
+          pointTopBefore: 'unset',
+          top: -tooltipBoxHeight
+        })
+        break
+      case 'left bottom':
+        this.setState({
+          margin: -70,
+          pointBorderAfter: 'transparent transparent white transparent',
+          pointBorderBefore: 'transparent transparent #d1d5da transparent',
+          pointMargin: -15,
+          pointTop: -15,
+          pointTopAfter: -20,
+          pointTopBefore: -23,
+          top: 40
+        })
+        break
+      case 'right bottom':
+        this.setState({
+          margin: -340,
+          pointBorderAfter: 'transparent transparent white transparent',
+          pointBorderBefore: 'transparent transparent #d1d5da transparent',
+          pointMargin: 260,
+          pointTop: -15,
+          pointTopAfter: -20,
+          pointTopBefore: -23,
+          top: 40
+        })
+        break
+    }
+  }
+
+  hoverIn = () => {
+    if (this.state.interval) {
+      clearTimeout(this.state.interval)
+      this.setState(
+        {
+          interval: null,
+          hover: true
+        },
+        this.tooltipPositionEval
+      )
+    } else {
+      this.setState(
+        {
+          hover: true
+        },
+        this.tooltipPositionEval
+      )
+    }
+  }
+
+  hoverOut = () => {
+    this.setState({
+      interval: setTimeout(() => {
+        this.setState({
+          hover: false
+        })
+      }, 100)
+    })
+  }
+
+  render() {
+    return (
+      <>
+        <HighlightedText
+          onMouseOver={this.hoverIn}
+          onMouseLeave={this.hoverOut}
+        >
+          <span id={`tooltip-text-${this.state.key}`}>{this.props.text}</span>
+        </HighlightedText>
+        {this.state.hover && (
+          <TooltipContainer
+            className="tooltip-container"
+            onMouseOver={this.hoverIn}
+            onMouseLeave={this.hoverOut}
+          >
+            <TooltipText
+              id={`tooltip-box-${this.state.key}`}
+              margin={this.state.margin}
+              width={this.state.width}
+              pointBorderAfter={this.state.pointBorderAfter}
+              pointBorderBefore={this.state.pointBorderBefore}
+              pointMargin={this.state.pointMargin}
+              pointTop={this.state.pointTop}
+              pointTopBefore={this.state.pointTopBefore}
+              pointTopAfter={this.state.pointTopAfter}
+              top={this.state.top}
+              bottom={this.state.bottom}
+            >
+              <div className="header">{this.state.header}</div>
+              <ReactMarkdown source={this.state.description} />
+            </TooltipText>
+          </TooltipContainer>
+        )}
+      </>
+    )
+  }
+}
+
+const HighlightedText = styled.span`
+  border-bottom: 1px black dotted;
+`
+
+const TooltipContainer = styled.div`
+  position: absolute;
+  display: inline-block;
+  z-index: 300000000;
+  background-color: white;
+`
+
+const TooltipText = styled.div`
+  padding: 8px 10px;
+  border: 1px solid #d1d5da;
+  border-radius: 3px;
+  background-color: white;
+  position: absolute;
+  z-index: 1;
+  top: ${props => {
+    if (props.top === 'unset') {
+      return 'unset'
+    } else {
+      return `${props.top}px`
+    }
+  }};
+  margin-left: ${props => props.margin || -70}px;
+  width: ${props => props.width || 400}px;
+
+  &:after,
+  &:before {
+    content: '';
+    position: absolute;
+    top: ${props => props.pointTop}%;
+    border-style: solid;
+    margin-left: ${props => props.pointMargin || -15}px;
+  }
+
+  &:after {
+    top: ${props => props.pointTopAfter}px;
+    left: 10%;
+    border-width: 10px;
+    border-color: ${props => props.pointBorderAfter};
+  }
+  &:before {
+    top: ${props => props.pointTopBefore}px;
+    left: 10%;
+    border-width: 11px;
+    border-color: ${props => props.pointBorderBefore};
+  }
+
+  .header {
+    font-size: 1.3em;
+    font-weight: bold;
+  }
+`
+
+export default Tooltip

static/docs/commands-reference/version.md

@@ -14,14 +14,14 @@ usage: dvc version [-h] [-q | -v]
 Running the command `dvc version` outputs the following information about the
 system/environment:
 
-| Type                                        | Detail                                                                                                                                                    |
-| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`DVC version`](#components-of-dvc-version) | Version of DVC (along with a Git commit hash in case of a development version)                                                                            |
-| `Python version`                            | Version of the Python being used for the project in which DVC is initialized                                                                              |
-| `Platform`                                  | Information about the operating system of the machine                                                                                                     |
-| [`Binary`](#what-we-mean-by-binary)         | Shows whether the package is installed from a binary release or source                                                                                    |
-| `Cache`                                     | [Type of links](/doc/user-guide/large-dataset-optimization#file-link-types-for-the-dvc-cache) supported between the DVC workspace and the cache directory |
-| `Filesystem type`                           | Shows the filesystem type (eg. ext4, FAT, etc.) and mount point of workspace and the cache directory                                                      |
+| Type                                        | Detail                                                                                                                                                                 |
+| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`DVC version`](#components-of-dvc-version) | Version of DVC (along with a Git commit hash in case of a development version)                                                                                         |
+| `Python version`                            | Version of the Python being used for the project in which DVC is initialized                                                                                           |
+| `Platform`                                  | Information about the operating system of the machine                                                                                                                  |
+| [`Binary`](#what-we-mean-by-binary)         | Shows whether the package is installed from a binary release or source                                                                                                 |
+| `Cache`                                     | [Type of links](/doc/user-guide/large-dataset-optimization#file-link-types-for-the-dvc-cache) supported between the DVC workspace and the <abbr>cache</abbr> directory |
+| `Filesystem type`                           | Shows the filesystem type (eg. ext4, FAT, etc.) and mount point of <abbr>workspace</abbr> and the cache directory                                                      |
 
 > If `dvc version` is executed outside a DVC workspace, the command outputs the
 > filesystem type of the current working directory.