Create a new documentation component `DocsExample` that allows to toggle between an example and its code

[MisRob]

🌱 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 language="html">
  <template #example>
    // Renders the example
  </template>
  <template #code>
    // Renders the source code
  </template>
</DocsExample>

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

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

should produce the following:

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

(2) The code sample related to the example would be passed via the #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 above the card:

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/kcard.vue#L431-L491
  • 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 and DocsShowCode and be responsible only for switching between them
  • Be careful to not refactor DocsShow and DocsShowCode to not cause regressions in the current documentation website
• Use the new DocsExample on the KCard documentation page to demonstrate it works

Out of scope

At this stage, we only want to focus on creating DocsExample . 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 switches between DocsShow and DocsShowCode
• [ ] There are no regressions in the documentation places that use DocsShow and DocsShowCode
• [ ] DocsExample is used in one place to demonstrate it works

[MisRob]

Labeling as "good first issue" since its pretty straightforward and can be tested easily, but note that it's medium size. Furthermore, if it's your first encounter with the documentation website, some time will be needed to understand the current documentation mechanism well.