Merge pull request #223 from indirectlylit/toc

work on documenting component api

README.md

@@ -142,7 +142,7 @@ The `DocsPageTemplate` component takes an optional Boolean prop called `apiDocs`
 
 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 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)
+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

docs/common/DocsPageTemplate/index.vue

@@ -24,6 +24,7 @@
           :key="i"
           :title="section.title"
           :anchor="section.anchor"
+          fullwidth
         >
           <component :is="section.component" :api="api[section.key]" />
         </DocsPageSection>
@@ -47,6 +48,20 @@
   import jsdocs from '~/jsdocs.js';
   import tableOfContents from '~/tableOfContents.js';
 
+  function sectionsForDefaultSlot(children) {
+    if (children === undefined) {
+      return [];
+    }
+    return children
+      .filter(
+        node =>
+          node.componentOptions &&
+          node.componentOptions.tag === DocsPageSection.name &&
+          node.componentOptions.propsData.anchor
+      )
+      .map(node => node.componentOptions.propsData);
+  }
+
   export default {
     name: 'DocsPageTemplate',
     components: {
@@ -70,28 +85,21 @@
         if (path !== '/') {
           path = path.replace(/\/$/, '');
         }
-        // Search for page
+        // search for page
         for (const section of tableOfContents) {
           for (const page of section.pages) {
             if (path === page.path) {
               return page;
             }
           }
         }
-        // Page not found
-        consola.error(`'${path}' not found in pages.js`);
+        // page not found
+        consola.error(`'${path}' not found`);
         return undefined;
       },
       pageSections() {
         // look at children for sections and extract links
-        const pageSections = this.$slots.default
-          .filter(
-            node =>
-              node.componentOptions &&
-              node.componentOptions.tag === DocsPageSection.name &&
-              node.componentOptions.propsData.anchor
-          )
-          .map(node => node.componentOptions.propsData);
+        const pageSections = sectionsForDefaultSlot(this.$slots.default);
         // add any applicable API sections
         this.apiSections.forEach(section => pageSections.push(section));
         return pageSections;

docs/common/DocsPageTemplate/jsdocs/EventsTable.vue

@@ -10,7 +10,7 @@
       </tr>
     </thead>
     <tbody>
-      <tr v-for="(event, i) in api" :key="i">
+      <tr v-for="(event, i) in publicApi" :key="i">
         <td class="first-col">
           <code>{{ event.name }}</code>
           <DocsAnchorTarget :anchor="`#event:${event.name}`" />
@@ -36,6 +36,16 @@
         required: true,
       },
     },
+    computed: {
+      publicApi() {
+        return this.api.filter(docItem => {
+          if (!docItem['tags']) {
+            return true;
+          }
+          return !docItem['tags'].some(tagObj => tagObj['title'] === 'ignore');
+        });
+      },
+    },
   };
 
 </script>

docs/common/DocsPageTemplate/jsdocs/PropsTable.vue

@@ -13,7 +13,7 @@
       </tr>
     </thead>
     <tbody>
-      <tr v-for="(prop, i) in api" :key="i">
+      <tr v-for="(prop, i) in publicApi" :key="i">
         <td class="first-col">
           <code>{{ prop.name }}</code>
           <DocsAnchorTarget :anchor="`#prop:${prop.name}`" />
@@ -50,6 +50,24 @@
         required: true,
       },
     },
+    computed: {
+      publicApi() {
+        /* parses items from jsdocs.js
+         * refs:
+         * - https://vue-styleguidist.github.io/docs/Documenting.html#ignoring-props
+         * - https://vue-styleguidist.github.io/docs/Documenting.html#available-tags
+         */
+        return this.api.filter(docItem => {
+          if (!docItem['tags']) {
+            return true;
+          }
+          if (docItem['tags']['ignore'] || docItem['tags']['deprecated']) {
+            return false;
+          }
+          return true;
+        });
+      },
+    },
   };
 
 </script>

docs/pages/glossary/index.vue

@@ -16,7 +16,7 @@
       <table style="max-width: 1000px">
         <thead>
           <tr>
-            <th style="min-width: 150px">
+            <th style="min-width: 200px">
               Term
             </th>
             <th>Part of speech</th>

docs/pages/icons/index.vue

@@ -9,6 +9,9 @@
       <p>
         Importantly, we reference icons by a token specific to the Kolibri Design System rather than Material's names, in order to make token references more meaningful to designers and developers.
       </p>
+      <p>
+        You can use the <DocsLibraryLink component="KIcon" /> and <DocsLibraryLink component="KLabeledIcon" /> components to easily insert any icon. Some other components such as links and buttons also provide props as shortcuts for easily inserting icons by token name.
+      </p>
     </DocsPageSection>
 
     <DocsPageSection title="Size and text" anchor="#size-text">

docs/pages/kcontentrenderer.vue

@@ -0,0 +1,15 @@
+<template>
+
+  <DocsPageTemplate apiDocs />
+
+</template>
+
+
+<script>
+
+  export default {};
+
+</script>
+
+
+<style lang="scss" scoped></style>

docs/pages/kdropdownmenu.vue

@@ -0,0 +1,25 @@
+<template>
+
+  <DocsPageTemplate apiDocs>
+    <DocsPageSection title="Overview" anchor="#overview">
+
+      <p>
+        Implements a button with a dropdown set of options, based on <DocsExternalLink text="Keen's UI Menu" href="https://josephuspaye.github.io/Keen-UI/#/ui-menu" />. See these docs to understand the current implementation of the options object array.
+      </p>
+      <p>
+        Note that this component may be deprecated in the future: <DocsGithubLink issue="164" />
+      </p>
+    </DocsPageSection>
+  </DocsPageTemplate>
+
+</template>
+
+
+<script>
+
+  export default {};
+
+</script>
+
+
+<style lang="scss" scoped></style>

docs/pages/kfixedgrid.vue

@@ -0,0 +1,24 @@
+<template>
+
+  <DocsPageTemplate apiDocs>
+    <DocsPageSection title="Overview" anchor="#overview">
+      <p>
+        Grid layout with a fixed number of columns. Use with <DocsLibraryLink component="KFixedGridItem" />.
+      </p>
+      <p>
+        For a responsive grid with a variable number of columns based on screen size, see <DocsLibraryLink component="KGrid" /> and <DocsLibraryLink component="KGridItem" />.
+      </p>
+    </DocsPageSection>
+  </DocsPageTemplate>
+
+</template>
+
+
+<script>
+
+  export default {};
+
+</script>
+
+
+<style lang="scss" scoped></style>

docs/pages/kfixedgriditem.vue

@@ -0,0 +1,24 @@
+<template>
+
+  <DocsPageTemplate apiDocs>
+    <DocsPageSection title="Overview" anchor="#overview">
+      <p>
+        For use within <DocsLibraryLink component="KFixedGrid" />.
+      </p>
+      <p>
+        For a responsive grid with a variable number of columns based on screen size, see <DocsLibraryLink component="KGrid" /> and <DocsLibraryLink component="KGridItem" />.
+      </p>
+    </DocsPageSection>
+  </DocsPageTemplate>
+
+</template>
+
+
+<script>
+
+  export default {};
+
+</script>
+
+
+<style lang="scss" scoped></style>

docs/pages/kgrid.vue

@@ -0,0 +1,35 @@
+<template>
+
+  <DocsPageTemplate apiDocs>
+    <DocsPageSection title="Overview" anchor="#overview">
+      <p>
+        Grid layout with a dynamic number of columns based on the current window width.
+      </p>
+      <p>
+        The grid will have:
+      </p>
+      <ul>
+        <li>4 columns for small windows (<code>width &lt; 840px</code>)</li>
+        <li>8 columns for medium windows (<code>840px &lt;= width &lt; 960px</code>)</li>
+        <li>12 columns for large windows (<code>960px &lt;= width</code>)</li>
+      </ul>
+      <p>
+        Use with <DocsLibraryLink component="KGridItem" />, which accept "layout objects" as props. These layout objects can define values for <code>span</code>, <code>alignment</code>, or both.
+      </p>
+      <p>
+        For a grid with a fixed number of columns, see <DocsLibraryLink component="KFixedGrid" /> and <DocsLibraryLink component="KFixedGridItem" />.
+      </p>
+    </DocsPageSection>
+  </DocsPageTemplate>
+
+</template>
+
+
+<script>
+
+  export default {};
+
+</script>
+
+
+<style lang="scss" scoped></style>

docs/pages/kgriditem.vue

@@ -0,0 +1,32 @@
+<template>
+
+  <DocsPageTemplate apiDocs>
+    <DocsPageSection title="Overview" anchor="#overview">
+
+      <p>
+        For use within <DocsLibraryLink component="KGrid" />.
+      </p>
+      <p>
+        Layout input objects can define values for <code>span</code>, <code>alignment</code>, or both. They can define different layouts for different screen sizes which is very convenient for quickly building responsive layouts.
+      </p>
+      <p>
+        If no span is defined for a particular grid item, it span the full width of the grid.
+      </p>
+      <p>
+        If no alignment is defined for a particular layout, the item's contents will be left-aligned.
+      </p>
+
+    </DocsPageSection>
+  </DocsPageTemplate>
+
+</template>
+
+
+<script>
+
+  export default {};
+
+</script>
+
+
+<style lang="scss" scoped></style>

docs/pages/kicon.vue

@@ -0,0 +1,19 @@
+<template>
+
+  <DocsPageTemplate apiDocs>
+    <DocsPageSection title="Overview" anchor="#overview">
+      See <DocsInternalLink href="icons" text="the page on icons" /> for design guidance and a list of available icons.
+    </DocsPageSection>
+  </DocsPageTemplate>
+
+</template>
+
+
+<script>
+
+  export default {};
+
+</script>
+
+
+<style lang="scss" scoped></style>

docs/pages/klabeledicon.vue

@@ -0,0 +1,15 @@
+<template>
+
+  <DocsPageTemplate apiDocs />
+
+</template>
+
+
+<script>
+
+  export default {};
+
+</script>
+
+
+<style lang="scss" scoped></style>

docs/pages/kmodal.vue

@@ -0,0 +1,19 @@
+<template>
+
+  <DocsPageTemplate apiDocs>
+    <DocsPageSection title="Overview" anchor="#overview">
+      For design guidance, see the page on <DocsInternalLink href="modals" text="modals" />.
+    </DocsPageSection>
+  </DocsPageTemplate>
+
+</template>
+
+
+<script>
+
+  export default {};
+
+</script>
+
+
+<style lang="scss" scoped></style>

docs/pages/kpagecontainer.vue

@@ -0,0 +1,15 @@
+<template>
+
+  <DocsPageTemplate apiDocs />
+
+</template>
+
+
+<script>
+
+  export default {};
+
+</script>
+
+
+<style lang="scss" scoped></style>

docs/pages/kradiobutton.vue

@@ -1,6 +1,6 @@
 <template>
 
-  <DocsPageTemplate>
+  <DocsPageTemplate apiDocs>
 
     <DocsPageSection title="Overview" anchor="#overview">
       <p>

docs/pages/kswitch.vue

@@ -1,6 +1,6 @@
 <template>
 
-  <DocsPageTemplate>
+  <DocsPageTemplate apiDocs>
 
     <DocsPageSection title="Overview" anchor="#overview">
       <DocsShow>