Psaní dokumentace se stalo snadným díky VuePress

Vždy bylo důležité vynaložit úsilí potřebné k navržení, naprogramování a realizaci něčeho, co splňuje několik kritérií:

• umožňuje rychlý přístup ke struktuře aplikace.
• umožňuje volně vyhledávat v obsahu
• poskytuje soubor technických informací o použitých řešeních.
• podporuje formátování textu a kód
• lze uložit na GitHub, nejlépe s možností snadného nasazení.

Není divu, že dokumentace je spojena s velkými výdaji. Na druhou stranu tým roste, onboarding generuje spoustu nákladů, a proto se podpora neustále ptá vývojářů na stejné otázky. V určitém okamžiku každému chybí ... VuePress.

VuePress je generátor statických stránek založený na systému Vue.js, který je skvělý pro tvorbu dokumentace. Dobrým příkladem může být dokumentace systému Vue.js sama o sobě.

VuePress umožňuje upravovat texty ve formátu Markdown pomocí komponent Vue, které konečně poskytují opravdu široké možnosti. Stačí začít dvěma příkazy:

npm install -g vuepress

vuepress dev

Ve výchozím nastavení se VuePress spouští v adresáři docs / a vytváří si v něm vlastní složku vuepress. Po zadání výše uvedených příkazů se automaticky spustí program Uzel a zobrazí dokumentaci na adrese localhost: 8080 /. Zde je příklad struktury souboru.

Při správné konfiguraci vygeneruje VuePress kompletní a velmi estetickou stránku. Jak můžete vidět na obrazovce výše, naše dokumentace obsahuje dvě vlastní komponenty - CodeHeading a ColorSample.

Jednodušším příkladem pro začátek bude CodeHeading.

CodeHeading.vue

Šablona:

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

Styly:

.code-heading {
 width: 100%;
 výška: 40px;
 line-height: 40px;
 velikost písma: 12px;
 margin-bottom: -20px;
 border-top-left-radius: 6px;
 border-top-right-radius: 6px;
 text-align: vlevo;
 padding: 0 20px;
 box-sizing: border-box;
 barva: bílá;

 &__špatný {
   barva pozadí: #cc0000;

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

 &__dobrý {
   barva pozadí: #3eaf7c;

   &::after {
     content: "DOBRÝ";
   }
 }

 &__default {
   barva pozadí: #4e6e8e;
 }
}

Scénář:

exportovat výchozí {
 props: {
   type: String
 },
 computed: {
   colorClass() {
     return this.type ? `code-heading__${this.type}` : "code-heading__default";
   }
 }
};

Jedná se o standardní syntaxi komponenty Vue.js, která je snadno dostupná v souborech Markdown. Zde je příklad implementace (/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');

Tímto způsobem jsme získali zcela čitelné řešení pro prezentaci příkladů práce s kódem.

Snad každý vývojář frontendů se setkal se situací, kdy mu chyběla reprezentace HEX nějaké barvy z grafického návrhu. A co kdybyste měli barvu vždy po ruce a mohli si určitou paletu předem zafixovat? Přesně tak - dokumentace nějakým způsobem umožňuje nás držet se standardu. Výsledek může vypadat následovně:

V tomto příkladu byla použita komponenta ColorPicker.vue. Ta slouží nejen k prezentaci dané barvy - kliknutím na kolečko automaticky zkopírujeme HEX kód do schránky.

Šablona:

<template>
  <div class="color-sample">
    <div class="color-sample__container">
      <div
        class="color-sample__circle"
        @click="copyToClipboard"
        :style="`background-color: ${ color }`"
        title="Kliknutím zkopírujete kód 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>(( jméno ))</strong><br/>
        (( barva ))
      </p>
    </div>
  </div>
</template>

Styly:

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

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

 &__kruh {
   šířka: 70px;
   výška: 70px;
   float: left;
   border-radius: 50%;
   display: flex;
   align-items: center;
   justify-content: center;
   margin-right: 20px;
   cursor: pointer;
   border: Rámeček: 1px solid #cfd4db;
 }

 &__input-wrapper {
   position: relative;
 }

 &__input {
   velikost písma: 12px;
   padding: 2px;
   border-radius: 2px;
   border: 0;
   display: inline-block;
   šířka: 60px;
 }

 &__input-overlay {
   position: absolute;
   top: 0;
   left: 0;
   vpravo: 0;
   dole: 0;
   barva pozadí: bílá;
   text-align: center;
 }
}

Scénář:

exportovat výchozí {
 props: {
   color: String,
   name: String
 },
 computed: {
   hexId() {
     return `color-${this.color.replace("#", "")}`;
   }
 },
 metody: {
   copyToClipboard() {
     const label = document.getElementById(this.hexId);
     label.select();
     document.execCommand("copy");
   }
 }
};

Příklad implementace (/docs/Design/colors.md):

Stojí za to věnovat pozornost vyhledávači, který byl zabudován do aplikace VuePress:

Na základě záhlaví v souborech Markdown to funguje automaticky. Konfigurace takto vytvořené dokumentace vypadá následovně:

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: "Dokumenty na GitHubu",
       odkaz: 'https://github.com/'
     }
   ]
 }
}

S vuepress sestavit můžeme okamžitě vygenerovat statické soubory HTML připravené k rychlé publikaci s plnou podporou aktiv.

Za zmínku stojí, že VuePress umožňuje automatické nasazení na různé platformy, včetně GitHub Pages. Kromě toho možnost vytvářet vlastní témata dělá z VuePress poměrně dobré řešení pro blogy.

Pokud ve vás výše uvedené příklady vzbudily zvědavost, pro více informací doporučuji seznámit se s oficiální dokumentací k VuePress projekt.

Přečtěte si více:

• Optimalizace kódu pomocí objektů dotazů
• Výukový kurz základů Vue.js. Jak začít s tímto frameworkem?
• Zabezpečení v balíčcích Javascript
• GraphQL: zkušenosti z výroby