Pisanie dokumentacji stało się łatwe dzięki VuePress

Zawsze ważną kwestią było podjęcie wysiłku niezbędnego do zaprojektowania, zaprogramowania i wdrożenia czegoś, co spełnia kilka kryteriów:

• pozwala szybko uzyskać dostęp do struktury aplikacji
• umożliwia swobodne przeszukiwanie treści
• zawiera zestaw informacji technicznych na temat zastosowanych rozwiązań
• obsługuje formatowanie tekstu i pliku kod
• mogą być przechowywane na GitHub, najlepiej z możliwością łatwego wdrożenia.

Nic dziwnego, że dokumentacja wiąże się z dużymi wydatkami. Z drugiej strony zespół rośnie, onboarding generuje wiele kosztów, a do tego dział wsparcia stale zadaje deweloperom te same pytania. W pewnym momencie wszyscy tracą ... VuePress.

VuePress jest statycznym generatorem stron opartym na Vue.js, który świetnie nadaje się do tworzenia dokumentacji. Dobrym przykładem może być dokumentacja samej aplikacji Vue.js.

VuePress pozwala na edycję tekstów w formacie Markdown z wykorzystaniem komponentów Vue, które finalnie dają naprawdę szeroki wachlarz możliwości. Wystarczy zacząć od dwóch poleceń:

npm install -g vuepress

vuepress dev

Domyślnie VuePress uruchamia się w katalogu docs / i tworzy w nim własny folder vuepress. Po wprowadzeniu powyższych poleceń, automatycznie uruchamia się aplikacja Węzeł i wyświetla dokumentację pod adresem localhost: 8080 /. Oto przykład struktury plików.

Przy odpowiedniej konfiguracji, VuePress wygeneruje kompletną i bardzo estetyczną stronę. Jak widać na powyższym screenie, nasza dokumentacja zawiera dwa niestandardowe komponenty - CodeHeading i ColorSample.

Prostszym przykładem na początek będzie CodeHeading.

CodeHeading.vue

Szablon:

<template>
  <div :class="[ 'code-heading', colorClass ]">
    <slot/>
  </div>
</template>

Style:

.code-heading {
 width: 100%;
 height: 40px;
 line-height: 40px;
 font-size: 12px;
 margin-bottom: -20px;
 border-top-left-radius: 6px;
 border-top-right-radius: 6px;
 text-align: left;
 padding: 0 20px;
 box-sizing: border-box;
 color: white;

 &__bad {
   kolor tła: #cc0000;

   &::after {
     content: "BAD";
   }
 }

 &__good {
   background-color: #3eaf7c;

   &::after {
     content: "GOOD";
   }
 }

 &__default {
   kolor tła: #4e6e8e;
 }
}

Skrypt:

export default {
 props: {
   type: String
 },
 computed: {
   colorClass() {
     return this.type ? `code-heading__${this.type}` : "code-heading__default";
   }
 }
};

Jest to standardowa składnia komponentu Vue.js, która jest łatwo dostępna w plikach Markdown. Oto przykład implementacji (/docs/Code/javacript.md):

const valueWrappers = wrapper.findAll('.change__value').wrappers;
expect(valueWrappers).to.have.lengthOf(2);

expect(valueWrappers[0].text()).to.equal('€ 5000');
expect(valueWrappers[1].text()).to.equal('0');

W ten sposób otrzymaliśmy w pełni czytelne rozwiązanie do prezentacji przykładów pracy z kodem.

Prawdopodobnie każdy programista frontendowy miał sytuację, w której brakowało mu reprezentacji HEX dowolnego koloru z projektu graficznego. A gdyby tak zawsze mieć kolor pod ręką i z góry ustalić określoną paletę? Zgadza się - dokumentacja w jakiś sposób zmusza nas do trzymania się standardu. Rezultat może wyglądać następująco:

W tym przykładzie wykorzystany został komponent ColorPicker.vue. Służy on nie tylko do prezentacji danego koloru - klikając na kółko, automatycznie skopiujemy kod HEX do schowka.

Szablon:

<template>
  <div class="color-sample">
    <div class="color-sample__container">
      <div
        class="color-sample__circle"
        @click="copyToClipboard"
        :style="`background-color: ${ color }`"
        title="Kliknij, aby skopiować kod HEX"
      >
        <div class="color-sample__input-wrapper">
          <input type="text" class="color-sample__input" :id="hexId" :value="color">
            <div class="color-sample__input-overlay" :style="`background-color: ${ color }`"></div>
        </div>
      </div>
      <p>
        <strong>(( nazwa ))</strong><br/>
        (( kolor ))
      </p>
    </div>
  </div>
</template>

Style:

.color-sample {
 display: inline-block;
 width: 45%;
 margin: 15px;

 &__container {
   display: flex;
   align-items: center;
 }

 &__circle {
   width: 70px;
   height: 70px;
   float: left;
   border-radius: 50%;
   display: flex;
   align-items: center;
   justify-content: center;
   margin-right: 20px;
   cursor: pointer;
   border: 1px solid #cfd4db;
 }

 &__input-wrapper {
   position: relative;
 }

 &__input {
   font-size: 12px;
   padding: 2px;
   border-radius: 2px;
   border: 0;
   display: inline-block;
   width: 60px;
 }

 &__input-overlay {
   position: absolute;
   top: 0;
   left: 0
   right: 0;
   bottom: 0;
   kolor tła: biały;
   text-align: center;
 }
}

Skrypt:

export default {
 props: {
   color: String,
   name: String
 },
 computed: {
   hexId() {
     return `color-${this.color.replace("#", "")}`;
   }
 },
 methods: {
   copyToClipboard() {
     const label = document.getElementById(this.hexId);
     label.select();
     document.execCommand("copy");
   }
 }
};

Przykład implementacji (/docs/Design/colors.md):

Warto zwrócić uwagę na wyszukiwarkę, która została wbudowana w VuePress:

Na podstawie nagłówków w plikach Markdown działa automatycznie. Konfiguracja dokumentacji wykonanej w ten sposób wygląda następująco:

module.exports = {
 title: 'Docs',
 themeConfig: {
   sidebar: [
     {
       title: 'General',
       collapsable: false,
       children: [
         'General/introduction.md',
         'General/installation.md'
       ]
     },
     {
       title: 'Design',
       collapsable: false,
       children: [
         'Design/colors.md',
         'Design/fonts.md',
         'Design/forms.md',
         'Design/layout.md'
       ]
     },
     {
       title: 'Code',
       collapsable: false,
       children: [
         'Code/general.md',
         'Code/javascript.md',
         'Code/scss.md',
         'Code/vue.md',
         'Code/translations.md',
         'Code/git.md',
         'Code/deployment.md'
       ]
     }
   ],
   nav: [
     {
       text: 'Knowledge',
       items: [
         { text: 'VueSchools', link: 'https://vueschool.io/' }
       ]
     },
     {
       text: 'Codest',
       link: 'https://codesthq.com'
     },
     {
       text: 'Docs on GitHub',
       link: 'https://github.com/'
     }
   ]
 }
}

Z vuepress budować możemy natychmiast wygenerować statyczne pliki HTML gotowe do szybkiej publikacji z pełną obsługą zasobów.

Warto wspomnieć, że VuePress umożliwia automatyczne wdrażanie na różnych platformach, w tym GitHub Pages. Ponadto możliwość tworzenia własnych motywów sprawia, że VuePress jest całkiem dobrym rozwiązaniem dla blogów.

Jeśli powyższe przykłady wzbudziły twoją ciekawość, po więcej informacji polecam zapoznać się z oficjalną dokumentacją VuePress projekt.

Czytaj więcej:

• Optymalizacja kodu za pomocą Query Objects
• Samouczek dotyczący podstaw Vue.js. Jak zacząć pracę z tym frameworkiem?
• Bezpieczeństwo w pakietach Javascript
• GraphQL: wnioski wyciągnięte z produkcji