Skip to content

Commit

Permalink
run prettier on readme
Browse files Browse the repository at this point in the history
  • Loading branch information
indirectlylit committed Dec 10, 2020
1 parent 2a4ecfe commit f8f5ab7
Showing 1 changed file with 19 additions and 31 deletions.
50 changes: 19 additions & 31 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
[![Netlify Status](https://api.netlify.com/api/v1/badges/9ae9ac56-7240-4480-b5a8-01645cb903ca/deploy-status)](https://app.netlify.com/sites/kolibri-design-system/deploys) ![Lint](https://github.com/learningequality/kolibri-design-system/workflows/Lint/badge.svg?branch=v0.2.x)


# Kolibri Design System

## Usage
Expand Down Expand Up @@ -29,7 +28,7 @@ You can also specify a particular version of the design system. For example, thi
yarn add https://github.com/learningequality/kolibri-design-system#v1.0.1
```

Importable components and utilities are available under the `lib` path, for example:
Importable components and utilities are available under the `lib` path, for example:

```javascript
import KButton from 'kolibri-design-system/lib/KButton';
Expand All @@ -41,7 +40,6 @@ The shared UI library is made available as source code, not a built distribution

The public API of the shared UI library is _only_ that which is documented in the documentation. Functionality which is not documented should be considered either experimental or a private implementation detail.


## Development of the documentation site

How to make updates to the Kolibri Design System
Expand All @@ -54,7 +52,6 @@ The shared UI library code is built from Vue, Javascript, and Sass. It requires

The documentation site is built using [NuxtJS](https://nuxtjs.org/) and [Vue](https://vuejs.org/). It requires the dependencies specified in the `devDependencies` attribute of `/package.json` to build and run. The documentation site can either be run locally using the Node.js development server, or exported as a static site and uploaded to a CDNde


### Running the documentation locally

Clone this repository using [Git](https://help.github.com/en/github/getting-started-with-github/set-up-git), optionally [forking](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) it first if you plan to submit changes.
Expand Down Expand Up @@ -91,15 +88,14 @@ You'll need version 10.x of Node.js installed. See the [Node Version Manager](ht

When setting up your text editor, it's useful to ignore the following directories:

* `node_modules`
* `.nuxt`
* `dist`
- `node_modules`
- `.nuxt`
- `dist`

You may also want to install syntax highlighters in your editor for Vue and SASS.

Finally, it's useful to have the Vue development tools installed in your web browser.


### Making changes to content

The documentation site is built using [NuxtJS](https://nuxtjs.org/) (configured in `/nuxt.config.js`) and [Vue](https://vuejs.org/).
Expand All @@ -110,26 +106,24 @@ Common components used in the documentation site are prefixed with `Docs*` and a

Layout:

* `<DocsPageTemplate />` - the main page template used by all pages
* `<DocsPageSection />` - sections within the page template with auto-generated anchor links
- `<DocsPageTemplate />` - the main page template used by all pages
- `<DocsPageSection />` - sections within the page template with auto-generated anchor links

Links:

* `<DocsAnchorTarget />` - for adding Anchor links to pages
* `<DocsExternalLink />` - links to an external website
* `<DocsInternalLink />` - links within the design system
- `<DocsAnchorTarget />` - for adding Anchor links to pages
- `<DocsExternalLink />` - links to an external website
- `<DocsInternalLink />` - links within the design system

Illustration:

* `<DocsShow />` - for showing a theme color
* `<DocsDoNot />` - for showing side-by-side "Do" and "Do not" illustrations
* `<DocsColorBlock />` - for showing a theme color
* `<DocsIconBlock />` - for showing an icon

- `<DocsShow />` - for showing a theme color
- `<DocsDoNot />` - for showing side-by-side "Do" and "Do not" illustrations
- `<DocsColorBlock />` - for showing a theme color
- `<DocsIconBlock />` - for showing an icon

All Kolibri shared components (for example `KButton`) are also available to be used within content. However, this should be limited to using them for _examples of usage_ only.


### Making changes to component docs

The `DocsPageTemplate` component takes an optional Boolean prop called `apiDocs`. When provided, the template will look for a shared library component with the same name, extract documentation for the component's props, events, slots, and methods, and display those at the bottom of the page after any other `DocsPageSection` components.
Expand All @@ -138,18 +132,16 @@ To make updates to this content, modify the library component directly. We suppo

JSDocs functionality is provided by the [`vue-docgen-api`](https://www.npmjs.com/package/vue-docgen-api) package. For more information, see [Documenting components](https://vue-styleguidist.github.io/docs/Documenting.html)


### Adding dependencies

There is one top-level `package.json` file, and:

* Dependencies used by the shared component library (`/lib`) are in `dependencies`
* Some other dependencies used by the shared component library (`/lib`) are expected/assumed to be provided by the library user
* _All_ other design system dependencies should be specified in `devDependencies`. This includes both build and run-time Nuxt-related dependencies
- Dependencies used by the shared component library (`/lib`) are in `dependencies`
- Some other dependencies used by the shared component library (`/lib`) are expected/assumed to be provided by the library user
- _All_ other design system dependencies should be specified in `devDependencies`. This includes both build and run-time Nuxt-related dependencies

See [issue #20](https://github.com/learningequality/kolibri-design-system/issues/20) for more information about how this situation could be improved.


### Design of the documentation site

The documentation site itself intentionally does _not_ conform to the design system it describes, for two reasons:
Expand All @@ -159,29 +151,25 @@ The documentation site itself intentionally does _not_ conform to the design sys

From a coding perspective this means that references to `~~/lib` code should in general only appear in `~/pages/` as illustrations of the shared UI library. However, we might decide on a case-by-case basis to have occasional exceptions to this rule. For example, we currently use `~~/lib/KResponsiveElementMixin` inside `~/common/Header` because it would be excessive to duplicate that functionality.


### Routing

We do _not_ use client-side routing. The reason is that we make extensive use of `#anchor` links, and there are many issues in both [NuxtJS](https://github.com/nuxt/nuxt.js/issues/5359) and [Vue Router](https://stackoverflow.com/questions/45201014/how-to-handle-anchors-bookmarks-with-vue-router/45206192) with mixing anchors and client-side routing. In practice, this means that there should be no instances of `<router-link>` or `<nuxt-link>` in documentation code.


### Import aliases

NuxtJS provides two webpack [import aliases](https://nuxtjs.org/guide/directory-structure#aliases):

* `~~/` points to the root of the repository
* `~/` points to the `/docs` directory
- `~~/` points to the root of the repository
- `~/` points to the `/docs` directory

These aliases should _not_ be used by code inside the `/lib` directory because external webpack configurations will not handle them correctly.


### Deployment

The documentation site is currently deployed to Netlifty automatically when changes are pushed to one of the primary branches. This is configured in the `/netlify.toml` file and authenticated with the [Netlify GitHub app](https://docs.netlify.com/configure-builds/repo-permissions-linking/#authentication-with-the-netlify-github-app).

Longer-term, we will likely want to transition to Google Cloud for more control of the deployment. Specifically, we'll want to


### SVG Icons

Icons are drawn from https://github.com/material-icons/material-icons and then converted to Vue components. This is currently pinned by the `yarn.lock`. If we upgrade it, we need to regenerate the Vue components by running:
Expand All @@ -190,7 +178,7 @@ Icons are drawn from https://github.com/material-icons/material-icons and then c
yarn run precompile-svgs
```

We also output a set of reStructuredText replacement strings into the file ``docs/rstIconReplacements.txt`` which can be used in
We also output a set of reStructuredText replacement strings into the file `docs/rstIconReplacements.txt` which can be used in
user docs based on Sphinx. To update this file, run

```bash
Expand Down

0 comments on commit f8f5ab7

Please sign in to comment.