From aae4ac54668b1958f2c89c7d55ce0c86aa0edb2b Mon Sep 17 00:00:00 2001 From: MisRob Date: Sun, 20 Aug 2023 11:07:48 +0200 Subject: [PATCH 1/7] Revamp developers documentation - Make it friendly for newcomers - Organize existing guidelines into more files - Organize information by focusing on important steps at first, and providing links to more detailed pages when relevant - Add a few new guidelines - Add guidance for contributors to README.md and CONTRIBUTING.md --- CONTRIBUTING.md | 15 ++ README.md | 258 +++--------------------- dev_docs/01_getting_started.md | 52 +++++ dev_docs/02_tips_and_troubleshooting.md | 22 ++ dev_docs/03_how_to_update_library.md | 77 +++++++ dev_docs/04_how_to_update_docs.md | 74 +++++++ dev_docs/05_icons.md | 48 +++++ dev_docs/06_misc.md | 44 ++++ 8 files changed, 356 insertions(+), 234 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 dev_docs/01_getting_started.md create mode 100644 dev_docs/02_tips_and_troubleshooting.md create mode 100644 dev_docs/03_how_to_update_library.md create mode 100644 dev_docs/04_how_to_update_docs.md create mode 100644 dev_docs/05_icons.md create mode 100644 dev_docs/06_misc.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..0b593280e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,15 @@ +# How can I contribute? + +1. 💻 Follow the [Getting started](./dev_docs/01_getting_started.md) to set up your development server. At the bottom of that page, you will also find links that will take you to guidelines for the most common tasks. +2. 🔍 Search for issues tagged as [help wanted](https://github.com/learningequality/kolibri-design-system/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22+no%3Aassignee+) or [good first issue](https://github.com/learningequality/kolibri-design-system/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22+no%3Aassignee). +3. 🗣️ Ask us for an assignment in the comments of an issue you've chosen. + +Note that in times of increased contributions activity, it may take us a few days to reply. If you don't hear from us within a week, please reach out via [Kolibri Design System GitHub Discussions](https://github.com/learningequality/kolibri-design-system/discussions). + +**❓ Where to ask questions** + +- For anything development related, refer to the [developer documentation](./dev_docs/) at first. Some answers may already be there. +- For questions related to a specific issue or assignment requests, use the corresponding issue's comments section. +- Visit [Kolibri Design System GitHub Discussions](https://github.com/learningequality/kolibri-design-system/discussions) to ask about anything related to contributing to Kolibri Design System, troubleshoot development server issues, or connect with other contributors. + +*Thank you for your interest in contributing to Kolibri Design System! The Kolibri project was founded by volunteers dedicated to helping make educational materials more accessible to those in need, and every contribution makes a difference.* diff --git a/README.md b/README.md index 58cdeae8a..98d1685e3 100644 --- a/README.md +++ b/README.md @@ -7,263 +7,53 @@ Note that the Kolibri Design System is not intended to be used as a dependency o If you are building a Kolibri plugin you should _not_ add the design system as a dependency because it will be made available as a dependency of Kolibri itself. -## Usage +## What is Kolibri Design System? -### Documentation +**[design-system.learningequality.org](https://design-system.learningequality.org)** is a resource for designers and developers who are building Kolibri products. It includes the design system patterns and the library of UI components. -See **[design-system.learningequality.org](https://design-system.learningequality.org)** for the latest design system documentation. +## How can I use it? -This contains resources for designers and developers who are building Kolibri products using the design system patterns and the shared UI library. +### Documentation -### Shared UI library +Refer to [design-system.learningequality.org](https://design-system.learningequality.org) to learn about the design system patterns and components, as well as the detailed technical documentation and guidance for the library components that are available for usage in Kolibri products. -The shared UI library is a node package containing front-end components, utilities, and style definitions supporting the Kolibri Design System and used in Learning Equality applications. +For the latest (not yet released) version, visit the design system website built from the `develop` branch at [develop--kolibri-design-system.netlify.app/](https://develop--kolibri-design-system.netlify.app/). -It is currently hosted only on Github, not NPM. To add a particular pinned version to your project using `yarn`, run: +### Component library -```bash -yarn add https://github.com/learningequality/kolibri-design-system -``` +The component library is a node package hosted on GitHub. It contains front-end components, utilities, and style definitions supporting the Kolibri Design System and used in Kolibri products. -You can also specify a particular version of the design system. For example, this would specify `v1.0.1`: +To add a particular pinned version to a project using `yarn`, for example `v1.0.1`, run: ```bash yarn add https://github.com/learningequality/kolibri-design-system#v1.0.1 ``` -Importable components and utilities are available under the `lib` path, for example: +Components and utilities will be accessible under the `lib` path. For example: ```javascript import KButton from 'kolibri-design-system/lib/KButton'; ``` +The library is provided as source code, rather than a pre-built distribution. A project using it needs to supply both build and runtime dependencies. -The shared UI library is made available as source code, not a built distribution, and requires the external application to supply both build and runtime dependencies such as webpack, Vue, and Sass. These requirements will eventually be specified in `/package.json` as `peerDependencies` - ref: [#20](https://github.com/learningequality/kolibri-design-system/issues/20). - -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 - -### Overview - -The design system has two primary components, the shared UI library (under `/lib`) and the documentation site (under `/docs`). - -The shared UI library code is built from Vue, Javascript, and Sass. It requires the dependencies specified under the `dependencies` and `peerDependencies` attributes of `/package.json`. An external application will import and functionality from `kolibri-design-system/lib` as [described in the documentation](https://kolibri-design-system.netlify.app), and then generate build artifacts as necessary for the application's specific deployment or distribution requirements. - -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. - -First, change to the directory where you cloned the repo: - -```bash -cd kolibri-design-system -``` - -Install the dependencies using `yarn`: - -```bash -yarn install -``` - -(Note: if you see a timeout error like `ESOCKETTIMEDOUT`, you can configure yarn with a higher timeout value [as described here](https://github.com/yarnpkg/yarn/issues/5540#issuecomment-374069461).) - -Run the development server using - -```bash -yarn dev -``` - -This will launch a documentation development server at `http://localhost:4000/`. It also launches a linter and auto-formatter based on the [`kolibri-tools`](https://github.com/learningequality/kolibri/tree/develop/packages/kolibri-tools) package. - -There are few other commands available: - -```bash -yarn dev-only # launch just the dev server without the linter and auto-formatter -yarn generate # build a static version of the site for upload to CDN -yarn lint-fix # run the linter and auto-formatter once -yarn lint-watch # run the linter in watch mode, without the auto-formatter -``` - -### Development environment - -You'll need version 10.x of Node.js installed. See the [Node Version Manager](https://github.com/nvm-sh/nvm) for help. - -When setting up your text editor, it's useful to ignore the following directories: - -* `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/). - -The directories and files in `/docs/pages/` are mapped by NuxtJS to URLs. Start with those files for making updates to documentation content. The table of contents, including sections and pages, are defined in `/docs/tableOfContents.js`. - -Common components used in the documentation site are prefixed with `Docs*` and available for use in all pages. - -Layout: - -* `` - the main page template used by all pages -* `` - sections within the page template with auto-generated anchor links - -Links: - -* `` - for creating anchor link targets -* `` - links to an external website -* `` - links to pages within the design system -* `` - links to library components with `` formatting - -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 - - -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. - -To make updates to this content, modify the library component directly. We support a combination of Markdown and JSDocs inside the components. - -JSDocs functionality is primarily 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). Note that we leverage a specific subset of the functionality described there. Documenting this is an [open issue](https://github.com/learningequality/kolibri-design-system/issues/222). - - -### 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 - -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: - -1. The user-interface of the site (links, buttons, headers, etc) is intentionally built _without_ depending on the Kolibri shared UI library. This helps ensure as we update the UI library, we only need to update content and examples in the documentation, not the implementation of the documentation. -2. From a design perspective, it's important that the documentation site looks and feels sufficiently distinct from the design patterns it describes, so that users do not mistakenly immitate it. Instead, users should focus on the patterns that are explicitly documented. - -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 - -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 web UI to run `yarn generate` and point at the created `dist` directory. - -Netlify is authenticated with the [Netlify GitHub app](https://docs.netlify.com/configure-builds/repo-permissions-linking/#authentication-with-the-netlify-github-app). - -Note that we currently use the deprecated Nuxt.js `mode: universal` flag, and should switch to the newer `target: static` flag. - - -### SVG Icons - -There are three sources of icons: - -- [Google Material Design Icons](https://github.com/material-icons/material-icons) (a version pinned in [yarn.lock](yarn.lock)) -- [Material Design Icons](https://github.com/Templarian/MaterialDesign-SVG) (a version pinned in [yarn.lock](yarn.lock)) -- [Custom Learning Equality icons](custom-icons) - -Icons from these sources are then converted to Vue components by our custom precompilation script. After updating any of these sources, we need to regenerate the Vue components by running: - -```bash -yarn run precompile-svgs -``` - -You can also regenerate just the custom icons which is faster: - -```bash -yarn run precompile-custom-svgs -``` - -One of these commands should be run after any icon changes. - -We don't expose all icons in our KDS public API. Only icons defined in [the icons definitions file](lib/KIcon/iconDefinitions.js) are exposed, and we use our custom aliases for them. +## How do I get help or give feedback? -In order to use icons in documentation we also output a set of reStructuredText replacement strings. These are added the file `docs/rstIconReplacements.txt` which can be used in docs based on Sphinx. The file is available for download from https://design-system.learningequality.org/icons/#rst +Contact us at the [Kolibri Design System GitHub Discussions](https://github.com/learningequality/kolibri-design-system/discussions). -This command should be run after any icon ID changes. - -```bash -yarn run pregenerate -``` +If you have found a bug, you can create a [Github issue](https://github.com/learningequality/kolibri-design-system/issues) following the instructions in the issue template. -#### Example: Upgrading Google Material Design Icons +## How can I contribute? -It is advised to commit changes at each step to make reviewing files other than those in *precompiled-icons/* easier, especially in case of large updates. +1. 💻 Follow the [Getting started](./dev_docs/01_getting_started.md) to set up your development server. At the bottom of that page, you will also find links that will take you to guidelines for the most common tasks. +2. 🔍 Search for issues tagged as [help wanted](https://github.com/learningequality/kolibri-design-system/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22+no%3Aassignee+) or [good first issue](https://github.com/learningequality/kolibri-design-system/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22+no%3Aassignee). +3. 🗣️ Ask us for an assignment in the comments of an issue you've chosen. -1. Run `yarn upgrade @material-icons/svg` -2. Run `yarn run precompile-svgs` -3. Review updates of all public icons defined in [the icons definitions file](lib/KIcon/iconDefinitions.js) +Note that in times of increased contributions activity, it may take us a few days to reply. If you don't hear from us within a week, please reach out via [Kolibri Design System GitHub Discussions](https://github.com/learningequality/kolibri-design-system/discussions). -Large upgrades can result in a colossal git diff which makes reviewing changes of selected public icons in detail difficult. To make such upgrades smoother, in addition to visually reviewing [icons in KDS documentation](https://design-system.learningequality.org/icons/#icons), you can use a report that is printed in a terminal as soon as the precompilation process ends. It contains all exposed icons aliases together with information about whether an icon has been updated or no. If it's been updated, git diff will be printed. +**❓ Where to ask questions** -4. Run `yarn run pregenerate` -5. Write down notes to the changelog about any public updates like visual changes of icons, updates of their aliases, and updates of reStructuredText replacement strings - -### Keen UI vendored files - -Several years ago, we vendored [Keen UI](https://github.com/JosephusPaye/Keen-UI). Since then, some of the components were updated occasionally to match Keen UI updates, but overall we use fairly old versions. We agreed not to follow Keen UI updates and consider forked components as "our own". Therefore, Keen UI components can be modified directly as needed. - -### Development in parallel with other applications - -If you are working on the design system library code in this repo and want to see local updates reflected in other applications that are using this library, then you will need to do a few things. - -1. While in the root of your local `kolibri-design-system` repository, run `yarn link`. -2. In the root of the application where you intend to use `kolibri-design-system` run `yarn link kolibri-design-system` and then `yarn install`. - -Now, when you run the application your changes in `kolibri-design-system` will be updated live where your app expects its dependency on `kolibri-design-system` to live. - -For example, given that you have `./kolibri` and `./kolibri-design-system` folders with their respective local repositories: - -```bash -# change to the KDS repo and add it to yarn's local package registry -cd ./kolibri-design-system -yarn link - -# change to the Kolibri repo and link to the local package -cd ../kolibri -yarn link kolibri-design-system - -# re-install dependencies -yarn install - -# run the Kolibri devserver -yarn run devserver -``` +- For anything development related, refer to the [developer documentation](./dev_docs/) at first. Some answers may already be there. +- For questions related to a specific issue or assignment requests, use the corresponding issue's comments section. +- Visit [Kolibri Design System GitHub Discussions](https://github.com/learningequality/kolibri-design-system/discussions) to ask about anything related to contributing to Kolibri Design System, troubleshoot development server issues, or connect with other contributors. -Now you're all set to see your changes to the Kolibri Design System working live in Kolibri! +*Thank you for your interest in contributing to Kolibri Design System! The Kolibri project was founded by volunteers dedicated to helping make educational materials more accessible to those in need, and every contribution makes a difference.* diff --git a/dev_docs/01_getting_started.md b/dev_docs/01_getting_started.md new file mode 100644 index 000000000..4149bfca0 --- /dev/null +++ b/dev_docs/01_getting_started.md @@ -0,0 +1,52 @@ +# Getting started + +The design system has two primary parts, the UI component library [`/lib`](../lib/) and the documentation site [`/docs`](../docs/). The following guidelines will help you set up a development environment so that you can update both. + +## Prerequisites + +You'll need version 10.x of Node.js installed. See the [Node Version Manager](https://github.com/nvm-sh/nvm) for help. + +## Development environment + +At first, [fork](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) this repository. + +Then, change to the directory where you cloned it: + +```bash +cd kolibri-design-system +``` + +Install the dependencies using `yarn`: + +```bash +yarn install +``` + +Finally, run the development server: + +```bash +yarn dev +``` + +This command will start a documentation development server at http://localhost:4000/. It will also run a linter and auto-formatter. + +There are few other commands available: + +```bash +yarn dev-only # launch just the dev server without the linter and auto-formatter +yarn lint-fix # run the linter and auto-formatter once +yarn lint-watch # run the linter in watch mode, without the auto-formatter +``` + +You're now ready to code! + +## Next steps + +- If you experienced troubles with the setup above or would like to get some development tips, you can visit [Tips and troubleshooting](./02_tips_and_troubleshooting.md). +- Our components are build in Vue 2. If you're not familiar with this framework, refer to [Vue 2 documentation](https://v2.vuejs.org/). +- If you'd like to update the component library, continue to [How to update the component library](./03_how_to_update_library.md). + +The guidelines referenced above should be sufficient for the most common tasks. There are a few additional developer documentation pages available. However, these pages contain information that is more internal in nature or related to specialized tasks: +- [How to update the documentation website](./04_how_to_update_docs.md) +- [Icons](./05_icons.md) +- [Miscellaneous](./06_misc.md) diff --git a/dev_docs/02_tips_and_troubleshooting.md b/dev_docs/02_tips_and_troubleshooting.md new file mode 100644 index 000000000..437d3ca0c --- /dev/null +++ b/dev_docs/02_tips_and_troubleshooting.md @@ -0,0 +1,22 @@ + +# Tips and troubleshooting + +Here, you can find development and troubleshooting tips. + +## `ESOCKETTIMEDOUT` error + +If you see a timeout error like `ESOCKETTIMEDOUT` during `yarn install`, you can configure yarn with a higher timeout value [as described here](https://github.com/yarnpkg/yarn/issues/5540#issuecomment-374069461). + +## Vue Devtools + +Vue Devtools is a useful browser extension for debugging and developing Vue applications. You can follow these [installation instructions](https://devtools.vuejs.org/guide/installation.html). + +## Text editor + +When setting up your text editor, it's useful to ignore the following directories: + +* `node_modules` +* `.nuxt` +* `dist` + +You may also want to install syntax highlighters in your editor for Vue and SASS. diff --git a/dev_docs/03_how_to_update_library.md b/dev_docs/03_how_to_update_library.md new file mode 100644 index 000000000..36b639976 --- /dev/null +++ b/dev_docs/03_how_to_update_library.md @@ -0,0 +1,77 @@ +# How to update the component library + +The design system has two primary parts, the UI component library [`/lib`](../lib/) and the documentation website [`/docs`](../docs/). The following guidelines will help you update the component library. For guidance on developing the documentation website, see [How to update the documentation website](./04_how_to_update_docs.md). + +## Prerequisites + +Your development server is set up and running as described in [Getting started](./01_getting_started.md). + +## Add/update a component + +Library components are located in [`/lib`](../lib/). If a component is made up of sub-components in separate files, it will typically be placed in a folder. + +**How to add a new component** + +1. Create a new component file in [`/lib`](../lib/) +2. In [KThemePlugin](../lib/KThemePlugin.js), import the component and make it globally accessible by registering it with `Vue.component` (see other components) + +See the section below to learn how to preview your new component. + +## Visually testing components updates + +There are two ways to visually test updates as you're developing: +- (1) In Kolibri Design System environment +- (2) In a product that uses Kolibri Design System + +See the two sections below for detailed guidance. + +Option (1) is simpler and sufficient as the first step, so we recommend starting that way. On certain occasions, it may be necessary to test an update in a product. You are welcome to try (2) if you'd like to, but typically we do not require contributors to do so, or we will provide support if needed. + +### (1) Preview updates in the Kolibri Design System environment + +The documentation development server can be used to visually test components updates in the following ways: + +**Playground page** + +TODO + +**Components documentation pages** + +The majority of existing components have documentation pages that often show live components in different states. One example of this can be seen on the KBreadcrumbs documentation page at http://localhost:4000/kbreadcrumbs. Its source code is located in [`/docs/pages/kbreadcrumbs.vue`](../docs/pages/kbreadcrumbs.vue). + +You can find links to documentation pages for existing components on the documentation website in the "Code library components" section at the bottom of the side navigation. + +If there is already a documentation page for a component, please ensure that any new updates don't break examples on the page. Additionally, you may also consider adding new examples to the documentation if applicable. See [How to update the documentation website](./04_how_to_update_docs.md) to find out more about updating documentation content. You can also review existing documentation pages in the [`/docs/pages`](../docs/pages) directory to familiarize yourself with the source code for the documentation. + +When creating a new component, it is recommended to add a new documentation page for it as described in the "Create a documentation page for a new component" section of [How to update the documentation website](./04_how_to_update_docs.md). Even if you are not specifically writing documentation, certain sections of the documentation page will be automatically generated from the component's props and related. + +### (2) Preview updates in a product + +To see local Kolibri Design System updates reflected in a product that is using it (such as [Kolibri Learning Platform](https://github.com/learningequality/kolibri) or [Kolibri Studio](https://github.com/learningequality/studio)): + +1. While in the root of your local `kolibri-design-system` repository, run `yarn link`. +2. In the root of the product where you intend to use `kolibri-design-system` run `yarn link kolibri-design-system` and then `yarn install`. + +Now, when you run the product your changes in `kolibri-design-system` will be updated live when running the product's development server. + +For example, to test Kolibri Design System in Kolibri Learning Platform (local `kolibri` repository): + +```bash +# change to the Kolibri Design System repository and add it to yarn's local package registry +cd ./kolibri-design-system +yarn link + +# change to the Kolibri repository and link it to the local Kolibri Design System package +cd ../kolibri +yarn link kolibri-design-system + +# re-install Kolibri dependencies +yarn install + +# run the Kolibri development server +yarn run devserver +``` + +Note that to be able to run the Kolibri development server, at first you need to have it set up as described in [Kolibri developer documentation](https://kolibri-dev.readthedocs.io/en/develop/getting_started.html). + +Now you're all set to see your changes to the Kolibri Design System working live in Kolibri! diff --git a/dev_docs/04_how_to_update_docs.md b/dev_docs/04_how_to_update_docs.md new file mode 100644 index 000000000..9deb388d6 --- /dev/null +++ b/dev_docs/04_how_to_update_docs.md @@ -0,0 +1,74 @@ +# How to update the documentation website + +The design system has two primary parts, the UI component library [`/lib`](../lib/) and the documentation website [`/docs`](../docs/). The following guidelines will help you update the documentation website. For guidance on developing the component library, see [How to update the component library](./04_how_to_update_library.md). + +## Prerequisites + +Your development server is set up and running as described in the [Getting started](./01_getting_started.md). + +## Updating content + +The documentation site is built using [NuxtJS](https://nuxtjs.org/) (configured in `/nuxt.config.js`) and [Vue](https://vuejs.org/). + +The directories and files in `/docs/pages/` are mapped by NuxtJS to URLs. Start with those files for making updates to documentation content. The table of contents, including sections and pages, are defined in `/docs/tableOfContents.js`. + +Common components used in the documentation site are prefixed with `Docs*` and available for use in all pages. + +Layout: + +* `` - the main page template used by all pages +* `` - sections within the page template with auto-generated anchor links + +Links: + +* `` - for creating anchor link targets +* `` - links to an external website +* `` - links to pages within the design system +* `` - links to library components with `` formatting + +Illustration: + +* `` - for showing a component +* `` - 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. + +## Updating the library components documentation + +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. + +To make updates to this content, modify the library component directly. We support a combination of Markdown and JSDocs inside the components. + +JSDocs functionality is primarily 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). Note that we leverage a specific subset of the functionality described there. Documenting this is an [open issue](https://github.com/learningequality/kolibri-design-system/issues/222). + +### Create a documentation page for a new component + +1. For a new component (`/lib/KNewComponent.vue`), create a new Vue file in [`/docs/pages`](../docs/pages) named after the component, except in lowercase (`/docs/pages/knewcomponent.vue`). +2. Add the following to `/docs/pages/knewcomponent.vue`: +```vue + +``` +3. Add a new entry to `pages` array in the `Section` with the title `'Code library components'` in [/docs/tableOfContents.js](../docs/tableOfContents.js): + ```javascript + new Page({ + path: '/knewcomponent', + title: 'KNewComponent', + isCode: true, + }), + ``` +4. See your new documentation page live at http://localhost:4000/knewcomponent (if it doesn't load, try to restart the development server) + +## 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 + +These aliases should _not_ be used by code inside the `/lib` directory because external webpack configurations will not handle them correctly. diff --git a/dev_docs/05_icons.md b/dev_docs/05_icons.md new file mode 100644 index 000000000..4953a1bcf --- /dev/null +++ b/dev_docs/05_icons.md @@ -0,0 +1,48 @@ +# Icons + +This page is all about Kolibri Design System icons. It includes information on our icon sources and provides guidelines on related workflows. + +## Sources and regenerating Vue components + +There are three sources of icons: + +- [Google Material Design Icons](https://github.com/material-icons/material-icons) (version pinned in [yarn.lock](yarn.lock)) +- [Material Design Icons](https://github.com/Templarian/MaterialDesign-SVG) (version pinned in [yarn.lock](yarn.lock)) +- [Custom Learning Equality icons]([custom-icons](../custom-icons/)) + +Icons from these sources are then converted to Vue components by our custom precompilation script. After updating any of these sources, we need to regenerate the Vue components by running: + +```bash +yarn run precompile-svgs +``` + +You can also regenerate just the custom icons which is faster: + +```bash +yarn run precompile-custom-svgs +``` + +One of these commands should be run after any icon changes. + +We don't expose all icons in our KDS public API. Only icons defined in [the icons definitions file](lib/KIcon/iconDefinitions.js) are exposed, and we use our custom aliases for them. + +In order to use icons in documentation we also output a set of reStructuredText replacement strings. These are added the file `docs/rstIconReplacements.txt` which can be used in docs based on Sphinx. The file is available for download from https://design-system.learningequality.org/icons/#rst + +This command should be run after any icon ID changes. + +```bash +yarn run pregenerate +``` + +### Example: Upgrading Google Material Design Icons + +It is advised to commit changes at each step to make reviewing files other than those in *precompiled-icons/* easier, especially in case of large updates. + +1. Run `yarn upgrade @material-icons/svg` +2. Run `yarn run precompile-svgs` +3. Review updates of all public icons defined in [the icons definitions file](lib/KIcon/iconDefinitions.js) + +Large upgrades can result in a colossal git diff which makes reviewing changes of selected public icons in detail difficult. To make such upgrades smoother, in addition to visually reviewing [icons in KDS documentation](https://design-system.learningequality.org/icons/#icons), you can use a report that is printed in a terminal as soon as the precompilation process ends. It contains all exposed icons aliases together with information about whether an icon has been updated or no. If it's been updated, git diff will be printed. + +4. Run `yarn run pregenerate` +5. Write down notes to the changelog about any public updates like visual changes of icons, updates of their aliases, and updates of reStructuredText replacement strings diff --git a/dev_docs/06_misc.md b/dev_docs/06_misc.md new file mode 100644 index 000000000..f75b42c59 --- /dev/null +++ b/dev_docs/06_misc.md @@ -0,0 +1,44 @@ +# Miscellaneous + +This is a collection of mostly internal notes. + +## Tech stack + +The shared UI library code is built from Vue, Javascript, and Sass. It requires the dependencies specified under the `dependencies` and `peerDependencies` attributes of `/package.json`. An external application will import and functionality from `kolibri-design-system/lib` as [described in the documentation](https://kolibri-design-system.netlify.app), and then generate build artifacts as necessary for the application's specific deployment or distribution requirements. + +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 CDN. + +## 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 + +See [issue #20](https://github.com/learningequality/kolibri-design-system/issues/20) for more information about how this situation could be improved. + +## 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 web UI to run `yarn generate` and point at the created `dist` directory. + +Netlify is authenticated with the [Netlify GitHub app](https://docs.netlify.com/configure-builds/repo-permissions-linking/#authentication-with-the-netlify-github-app). + +Note that we currently use the deprecated Nuxt.js `mode: universal` flag, and should switch to the newer `target: static` flag. + +## Design of the documentation site + +The documentation site itself intentionally does _not_ conform to the design system it describes, for two reasons: + +1. The user-interface of the site (links, buttons, headers, etc) is intentionally built _without_ depending on the Kolibri shared UI library. This helps ensure as we update the UI library, we only need to update content and examples in the documentation, not the implementation of the documentation. +2. From a design perspective, it's important that the documentation site looks and feels sufficiently distinct from the design patterns it describes, so that users do not mistakenly immitate it. Instead, users should focus on the patterns that are explicitly documented. + +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. + +## Keen UI vendored files + +Several years ago, we vendored [Keen UI](https://github.com/JosephusPaye/Keen-UI). Since then, some of the components were updated occasionally to match Keen UI updates, but overall we use fairly old versions. We agreed not to follow Keen UI updates and consider forked components as "our own". Therefore, Keen UI components can be modified directly as needed. From 6667321dd22039a63e6cc5bea62aa2577bc45d89 Mon Sep 17 00:00:00 2001 From: MisRob Date: Sun, 27 Aug 2023 16:15:50 +0200 Subject: [PATCH 2/7] Add playground --- dev_docs/03_how_to_update_library.md | 8 +++-- dev_docs/04_how_to_update_docs.md | 2 +- docs/pages/playground.vue | 50 ++++++++++++++++++++++++++++ 3 files changed, 57 insertions(+), 3 deletions(-) create mode 100644 docs/pages/playground.vue diff --git a/dev_docs/03_how_to_update_library.md b/dev_docs/03_how_to_update_library.md index 36b639976..baa94c013 100644 --- a/dev_docs/03_how_to_update_library.md +++ b/dev_docs/03_how_to_update_library.md @@ -4,7 +4,7 @@ The design system has two primary parts, the UI component library [`/lib`](../li ## Prerequisites -Your development server is set up and running as described in [Getting started](./01_getting_started.md). +Your development server is set up and running at http://localhost:4000/ as described in [Getting started](./01_getting_started.md). ## Add/update a component @@ -33,7 +33,11 @@ The documentation development server can be used to visually test components upd **Playground page** -TODO +Open [/docs/pages/playground.vue](../docs/pages/playground.vue) and add a component you're working on there. Then, as you're developing, you will see it update live at http://localhost:4000/playground. See an example in the playground file. + +If you are working on a new component, make sure to register it first in `KThemePlugin`, as described in the "How to add a new component" section above, in order to make it available on the playground page. + +Please do not commit any updates to the playground file as it's meant as your local preview only. This will help other developers have it ready for their own work. **Components documentation pages** diff --git a/dev_docs/04_how_to_update_docs.md b/dev_docs/04_how_to_update_docs.md index 9deb388d6..443cc8c4d 100644 --- a/dev_docs/04_how_to_update_docs.md +++ b/dev_docs/04_how_to_update_docs.md @@ -4,7 +4,7 @@ The design system has two primary parts, the UI component library [`/lib`](../li ## Prerequisites -Your development server is set up and running as described in the [Getting started](./01_getting_started.md). +Your development server is set up and running at http://localhost:4000/ as described in the [Getting started](./01_getting_started.md). ## Updating content diff --git a/docs/pages/playground.vue b/docs/pages/playground.vue new file mode 100644 index 000000000..bf32354b2 --- /dev/null +++ b/docs/pages/playground.vue @@ -0,0 +1,50 @@ + + + + From 4ebf42d6d19116e14e6a0afa2080b27a27c6935c Mon Sep 17 00:00:00 2001 From: MisRob Date: Tue, 29 Aug 2023 13:56:54 +0200 Subject: [PATCH 3/7] Few wording tweaks --- CONTRIBUTING.md | 2 ++ README.md | 1 + dev_docs/03_how_to_update_library.md | 6 +++--- dev_docs/04_how_to_update_docs.md | 2 +- 4 files changed, 7 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0b593280e..19f17f984 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,5 @@ + + # How can I contribute? 1. 💻 Follow the [Getting started](./dev_docs/01_getting_started.md) to set up your development server. At the bottom of that page, you will also find links that will take you to guidelines for the most common tasks. diff --git a/README.md b/README.md index 98d1685e3..f71be6b7d 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,7 @@ Contact us at the [Kolibri Design System GitHub Discussions](https://github.com/ If you have found a bug, you can create a [Github issue](https://github.com/learningequality/kolibri-design-system/issues) following the instructions in the issue template. + ## How can I contribute? 1. 💻 Follow the [Getting started](./dev_docs/01_getting_started.md) to set up your development server. At the bottom of that page, you will also find links that will take you to guidelines for the most common tasks. diff --git a/dev_docs/03_how_to_update_library.md b/dev_docs/03_how_to_update_library.md index baa94c013..f7b19d28a 100644 --- a/dev_docs/03_how_to_update_library.md +++ b/dev_docs/03_how_to_update_library.md @@ -25,7 +25,7 @@ There are two ways to visually test updates as you're developing: See the two sections below for detailed guidance. -Option (1) is simpler and sufficient as the first step, so we recommend starting that way. On certain occasions, it may be necessary to test an update in a product. You are welcome to try (2) if you'd like to, but typically we do not require contributors to do so, or we will provide support if needed. +Option (1) is simpler and sufficient as the first step, so we recommend starting that way. On certain occasions, it may be necessary to test an update in a product. If you're a contributor, you are welcome to try (2) as well, but typically we do not require contributors to do so, or we will provide support if needed. ### (1) Preview updates in the Kolibri Design System environment @@ -35,13 +35,13 @@ The documentation development server can be used to visually test components upd Open [/docs/pages/playground.vue](../docs/pages/playground.vue) and add a component you're working on there. Then, as you're developing, you will see it update live at http://localhost:4000/playground. See an example in the playground file. -If you are working on a new component, make sure to register it first in `KThemePlugin`, as described in the "How to add a new component" section above, in order to make it available on the playground page. +If you are working on a new component, make sure to register it first in `KThemePlugin` as described in the "How to add a new component" section above in order to make it available on the playground page. Please do not commit any updates to the playground file as it's meant as your local preview only. This will help other developers have it ready for their own work. **Components documentation pages** -The majority of existing components have documentation pages that often show live components in different states. One example of this can be seen on the KBreadcrumbs documentation page at http://localhost:4000/kbreadcrumbs. Its source code is located in [`/docs/pages/kbreadcrumbs.vue`](../docs/pages/kbreadcrumbs.vue). +The majority of existing components have documentation pages that often show live components in different states. One example of this can be seen on the `KBreadcrumbs` component documentation page at http://localhost:4000/kbreadcrumbs. The documentation page source code is located in [`/docs/pages/kbreadcrumbs.vue`](../docs/pages/kbreadcrumbs.vue). You can find links to documentation pages for existing components on the documentation website in the "Code library components" section at the bottom of the side navigation. diff --git a/dev_docs/04_how_to_update_docs.md b/dev_docs/04_how_to_update_docs.md index 443cc8c4d..c3b278b79 100644 --- a/dev_docs/04_how_to_update_docs.md +++ b/dev_docs/04_how_to_update_docs.md @@ -1,6 +1,6 @@ # How to update the documentation website -The design system has two primary parts, the UI component library [`/lib`](../lib/) and the documentation website [`/docs`](../docs/). The following guidelines will help you update the documentation website. For guidance on developing the component library, see [How to update the component library](./04_how_to_update_library.md). +The design system has two primary parts, the UI component library [`/lib`](../lib/) and the documentation website [`/docs`](../docs/). The following guidelines will help you update the documentation website. For guidance on developing the component library, see [How to update the component library](./03_how_to_update_library.md). ## Prerequisites From cabbfbd4bbdc5d2f192cc276a61654cc4d2036ee Mon Sep 17 00:00:00 2001 From: MisRob Date: Tue, 29 Aug 2023 13:58:01 +0200 Subject: [PATCH 4/7] Add contact links to the issue template chooser --- .github/ISSUE_TEMPLATE/config.yml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 3ba13e0ce..18d4fe42e 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1 +1,8 @@ blank_issues_enabled: false +contact_links: + - name: Kolibri GitHub Discussions + url: https://github.com/learningequality/kolibri/discussions + about: Please ask general questions about contributing to Kolibri or report development server issues here. + - name: Learning Equality Community Forum + url: https://community.learningequality.org/ + about: Ask and answer questions about Learning Equality's products and tools, share your experiences using Kolibri, and connect with users around the world. From 84ee1a8975301ccc7d56403b12945f97a56e89f5 Mon Sep 17 00:00:00 2001 From: MisRob Date: Tue, 19 Sep 2023 17:31:43 +0200 Subject: [PATCH 5/7] Add file watchers limit error guidance --- dev_docs/02_tips_and_troubleshooting.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/dev_docs/02_tips_and_troubleshooting.md b/dev_docs/02_tips_and_troubleshooting.md index 437d3ca0c..ec18724b8 100644 --- a/dev_docs/02_tips_and_troubleshooting.md +++ b/dev_docs/02_tips_and_troubleshooting.md @@ -7,6 +7,11 @@ Here, you can find development and troubleshooting tips. If you see a timeout error like `ESOCKETTIMEDOUT` during `yarn install`, you can configure yarn with a higher timeout value [as described here](https://github.com/yarnpkg/yarn/issues/5540#issuecomment-374069461). +## `System limit for number of file watchers reached` error + +If you see this error when running the development server, you can try to follow [this advice](https://stackoverflow.com/questions/55763428/react-native-error-enospc-system-limit-for-number-of-file-watchers-reached/55763478#55763478). + + ## Vue Devtools Vue Devtools is a useful browser extension for debugging and developing Vue applications. You can follow these [installation instructions](https://devtools.vuejs.org/guide/installation.html). From 9024b2c5b815d892414ae5adb44ccb2dc9a8b7d9 Mon Sep 17 00:00:00 2001 From: MisRob Date: Tue, 19 Sep 2023 17:34:30 +0200 Subject: [PATCH 6/7] Improve discoverability of troubleshooting guidelines --- dev_docs/01_getting_started.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/dev_docs/01_getting_started.md b/dev_docs/01_getting_started.md index 4149bfca0..90b5f9f56 100644 --- a/dev_docs/01_getting_started.md +++ b/dev_docs/01_getting_started.md @@ -6,6 +6,10 @@ The design system has two primary parts, the UI component library [`/lib`](../li You'll need version 10.x of Node.js installed. See the [Node Version Manager](https://github.com/nvm-sh/nvm) for help. +## Troubleshooting + +If you experience any problems with the setup below, see if you can find a similar issue in [Tips and troubleshooting](./02_tips_and_troubleshooting.md). + ## Development environment At first, [fork](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) this repository. From 9e3731ab119ca2ac47ef70253bd12022f99ff564 Mon Sep 17 00:00:00 2001 From: MisRob Date: Tue, 19 Sep 2023 17:36:45 +0200 Subject: [PATCH 7/7] Specify yarn version --- dev_docs/01_getting_started.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/dev_docs/01_getting_started.md b/dev_docs/01_getting_started.md index 90b5f9f56..d8d0005be 100644 --- a/dev_docs/01_getting_started.md +++ b/dev_docs/01_getting_started.md @@ -4,7 +4,8 @@ The design system has two primary parts, the UI component library [`/lib`](../li ## Prerequisites -You'll need version 10.x of Node.js installed. See the [Node Version Manager](https://github.com/nvm-sh/nvm) for help. +- Node.js 10.x (see [Node Version Manager](https://github.com/nvm-sh/nvm)) +- Yarn 1.x ## Troubleshooting