# Documentation Guidelines

At Storefront UI, we know that documentation is key—both for users of the components as well as for (new and existing) contributors. We aim for complete, correct and easy to understand docs for our components and the project in general.

This guide explains how different parts of the documentation play together and how contributors can help improving it.

# The Basic Setup

Different parts of documentation focus on different aspects, which is why they are located in various places:

  • The docs you read now are served via VuePress, a Markdown template-driven engine, perfect for general information about Storefront UI, mostly written in prose. The .md files (and some configuration files) located under packages/vue/docs/ serve this purpose.
  • Storybook stories may also be considered documentation, with a more formal and programmatic approach, focusing on characteristics of components. These .stories.js files reside next to the component's source code inside packages/vue/src/components/.
  • Some documentation may be found inline, i.e. inside source code. Important information for users is extracted automatically into other parts (e.g. slots are described in HTML comments but extracted into our main VuePress docs).

# Prose Documentation

Hand-written documentation (like the one you are reading now) takes place in Markdown files inside packages/vue/docs/. It follows less strict/formal rules but rather has to be addressed individually.

# Storybook Stories

WIP

This part is not finalized yet.

# Auto-generated Docs from Source Code

Inline source code documentation tends to be up-to-date with the code it describes. In order to reduce redundancy, out-of-date errors and work for maintainers and contributors, we try to automate documentation generation as much as possible. This is an ongoing endeavor but already works well for our components docs.

# Components Docs

The generation of our components documentation is automated. By running the yarn/npm task docs:vuecomponents which triggers the create-vue-components-docs.js script, the following sources are crawled and combined into the final component docs file, ready to serve via VuePress:

  • The location of the component as it describes
    • its atomic type (atom, molecule, organism),
    • its names (with and without Sf prefix),
    • the additional files of which it is composed (HTML, SCSS, etc.) and
    • whether it contains internal components.
  • The SCSS style file because it holds
    • the CSS modifiers (with an optional descriptions) and
    • the SCSS variables.
  • The Vue files are parsed for
    • props,
    • slots and
    • events.
  • Internal components' Vue files are parsed the same way and inserted into their parent's component docs.
  • Each component can provide an additional Markdown (MD) file for additional information which is then inserted into the final MD. They contain
    • a description of the component's purpose,
    • a common usage example and
    • a deep link into the component's (main) storybook page.

The final file is then saved as ComponentName.md to packages/vue/docs/components/.

TIP

Being a generated asset, this directory is excluded from VCS. Altering files here has no enduring effect.

In order to include the components docs in the VuePress navigation, they are also referenced in the appropriate VuePress config files (.vuepress/config.js and .vuepress/enhanceApp.js). Mind that altering the @components-docs comment markers in these files may lead to the script not being able to automatically insert the generated docs.

TIP

Make sure to run the generation script when adding/moving/removing components and after manual changes to the VuePress configuration files. On success, these changes need to be committed to VCS.

Documentation contributors need to know, where to add which type of documentation in which format. See the following Syntax chapters for reference.

# Syntax inside Inside Vue files

Props: Use normal block-comment style (with double-asterisk) for descriptions. Example:

/**
 * Product title
 */
title: {
  type: String,
  required: true
}

Slots: Use HTML-comment style with @slot prepended for descriptions. The slot name and bindings are inserted automatically. Example:

<!-- @slot Custom markup for previous page button -->
<slot name="prev" v-bind="{isDisabled: canGoPrev, go: goPrev}" >

Events: Use block-comment style (with double-asterisk) for descriptions and the @event identifier for the event name. Example:

/**
 * Library loaded event, the library is ready and the map is initialising
 *
 * @event 'library:loaded'
 * @type null
 */
this.$emit("library:loaded");

Multiline descriptions are merged into a single line, joined by dots (if necessary).

# Syntax inside CSS Modifiers

Use normal block-comment style (with single-asterisk) for descriptions. Example:

.sf-badge--full-width {
  /* @modifier This is the full-width modifier.
   * (Multiple lines get concatenated) */
  width: 100%;
}

By using the @no-docs annotation instead, you can exclude a modifier from being added to the modifiers list.

.sf-accordion-item__header-icon--up {
  /* @no-docs */
  transform: rotate(180deg);
}

Single-asterisk style was chosen so it doesn't interfere with the SASS parser logic. For the same reason, the comment has to be inside the modifier definition block it belongs to.

# Syntax inside Additional Component Info

The MD file for additional component information has to be named exactly like the component (with Sf prefix) and contain both (h1) headlines component-description and common-usage. Example:

# component-description
Arrow component for sliders and navigation.

# common-usage
<br>
<SfArrow />

```html 
<template>
  <SfArrow />
</template>

<script>
import { SfArrow } from '@storefront-ui/vue'

export default {
  components: {
    SfArrow
  }
}
</script>
```