From f8f5ab7b1f1763d1c31ce2aa8131ca39261e9b7d Mon Sep 17 00:00:00 2001 From: Devon Rueckner Date: Thu, 10 Dec 2020 10:17:42 -0800 Subject: [PATCH] run prettier on readme --- README.md | 50 +++++++++++++++++++------------------------------- 1 file changed, 19 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 330c8c271..904acb274 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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'; @@ -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 @@ -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. @@ -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/). @@ -110,26 +106,24 @@ Common components used in the documentation site are prefixed with `Docs*` and a Layout: -* `` - the main page template used by all pages -* `` - sections within the page template with auto-generated anchor links +- `` - the main page template used by all pages +- `` - sections within the page template with auto-generated anchor links Links: -* `` - for adding Anchor links to pages -* `` - links to an external website -* `` - links within the design system +- `` - for adding Anchor links to pages +- `` - links to an external website +- `` - links within the design system Illustration: -* `` - for showing a theme color -* `` - for showing side-by-side "Do" and "Do not" illustrations -* `` - for showing a theme color -* `` - for showing an icon - +- `` - for showing a theme color +- `` - for showing side-by-side "Do" and "Do not" illustrations +- `` - for showing a theme color +- `` - 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. @@ -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: @@ -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 `` or `` 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: @@ -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