🌱 Are you new to the codebase? Welcome! Please see the contributing guidelines.

Desired behavior

Create a new documentation component DocsExample that toggles between an example and its code on the documentation website.

<DocsExample>

  // The default slot renders the example

  <template #code>
     // The code slot renders code snippet(s)
     <DocsShowCode language="html">
     
     </DocsShowCode>
     
     <DocsShowCode language="javascript">
     
     </DocsShowCode>
  </template>
</DocsExample>

Here is one example demonstrating the expected visual output. For this KCardGrid demonstration (source, output), the new

<DocsExample language="html">
  <KCardGrid ...>
       ...
  </KCardGrid>

  <template #code>
    <DocsShowCode language="html">
       <KCardGrid ...>
          ...
        </KCardGrid>
     </DocsShowCode>

    <DocsShowCode language="javascript">
      export default { 
        ...
       }     
     </DocsShowCode>
  </template>
</DocsExample>

should produce the following:

(1) On an initial page load, we'd only show the card grid passed via the default slot

(2) The code sample(s) related to the example would be passed via placing DocsShowCode(s) to #code slot

(3) DocsExample would render a toggle button to "View code"/"Hide code" in its top right corner. Clicking it would show/hide the code sample(s) above the card grid:

The overall experience would be similar to that of the Vuetify documentation:

Current behavior

Right now we show code above or below the example, or not at all, and there is no way to toggle it.

The Value Add

• Consistency
• Conciseness

Guidance

• Understand how the documentation website is built and what's the general function of documentation components
  • dev_docs/04_how_to_update_docs.md#updating-content
• Familiarize yourself closely with the DocsShow and DocsShowCode and how they are used on documentation pages:
  • docs/pages/kcardgrid.vue#L248-L300
  • docs/common/DocsShow.vue
  • docs/common/DocsShowCode
• Then create a new component DocsExample that produces the "Desired behavior"
  • Under the hood, this component should utilize DocsShow to render the example
  • However it shouldn't internally use DocsShowCode since in some situations, we need to provide more code snippets in different languages related to one example. Therefore, DocsShowCode will be provided from outside as demonstrated above.
  • Be careful to not refactor DocsShow and DocsShowCode to not cause regressions in the current documentation website

Out of scope

At this stage, we only want to focus on creating DocsExample and using it at one place to demonstrate it works. Please do not refactor all examples on all website pages with it.

Acceptance criteria

• There is a new DocsExample documentation component as specified above
• DocsExample internally utilizes DocsShow
• DocsExample internally doesn't utilize DocsShowCode but rather receives it via the #code slot
• DocsExample can render multiple DocsShowCode snippets in various languages
• There are no regressions in the documentation places that use DocsShow and DocsShowCode
• DocsExample is used in the given KCardGrid documentation example