From 0e6bb474a879a01a9a5d0dd6984d2f2a13af1c51 Mon Sep 17 00:00:00 2001
From: Devon Rueckner <devon.rueckner@gmail.com>
Date: Tue, 17 Nov 2020 12:33:16 -0800
Subject: [PATCH] add documentation about using icons in rst

---
 docs/pages/icons/index.vue | 29 +++++++++++++++++++++++++++++
 nuxt.config.js             |  5 +++++
 2 files changed, 34 insertions(+)

diff --git a/docs/pages/icons/index.vue b/docs/pages/icons/index.vue
index ab8d57ad7..1dfd5e3d3 100644
--- a/docs/pages/icons/index.vue
+++ b/docs/pages/icons/index.vue
@@ -80,6 +80,19 @@
       <p>If the default Material icon library and/or community-contributed libraries are insufficient, use <DocsExternalLink href="https://material.io/design/iconography/system-icons.html" text="Material's icon creation guidelines" /> to create a new one.</p>
     </DocsPageSection>
 
+    <DocsPageSection title="Usage in documentation" anchor="#rst">
+      <p>
+        For use in documentation such as the <DocsExternalLink href="https://kolibri.readthedocs.io/" text="Kolibri User Docs" />, all icons above have <DocsExternalLink href="https://docutils.sourceforge.io/docs/ref/rst/directives.html#directives-for-substitution-definitions" text="substitutions" /> available in reStructuredText replacement syntax below:
+      </p>
+      <textarea v-model="text" class="replacements code" readonly></textarea>
+      <p>
+        Copy and paste it into a file such as <code>rstIconReplacements.txt</code> and then add it to your <code>conf.py</code> file <DocsExternalLink href="https://github.com/learningequality/kolibri-docs/blob/d582797e0d62d1482501954b6d0680031bce18cd/docs/conf.py#L174-L181" text="like this" />.
+      </p>
+      <p>
+        Then in <code>*.rst</code> files you can use, for example, <code>|video|</code> to insert the <KIcon icon="video" /> video icon. Note that these icons will <em>not</em> have screen-reader-accessible labels associated with them, so they should always be accompanied by descriptive text.
+      </p>
+    </DocsPageSection>
+
   </DocsPageTemplate>
 
 </template>
@@ -87,12 +100,18 @@
 
 <script>
 
+  import text from '../../rstIconReplacements.txt';
   import IconTable from './IconTable';
 
   export default {
     components: {
       IconTable,
     },
+    computed: {
+      text() {
+        return text;
+      },
+    },
   };
 
 </script>
@@ -105,4 +124,14 @@
     fill: blue !important;
   }
 
+  .replacements {
+    display: block;
+    width: 100%;
+    height: 100px;
+    font-size: smaller;
+    white-space: pre;
+    border: 1px solid #dedede;
+    border-radius: 4px;
+  }
+
 </style>
diff --git a/nuxt.config.js b/nuxt.config.js
index 3d9d1a3c6..43feb466c 100644
--- a/nuxt.config.js
+++ b/nuxt.config.js
@@ -42,6 +42,11 @@ export default {
         loader: 'svg-icon-inline-loader',
         exclude: /node_modules/,
       });
+      // allow this file to be displayed
+      config.module.rules.push({
+        test: /rstIconReplacements.txt/,
+        loader: 'raw-loader',
+      });
       config.devtool = 'source-map';
     },
     cssSourceMap: true,