Dokumentatsiooni kirjutamine on muutunud lihtsaks tänu VuePressile

See on alati olnud oluline küsimus, et teha vajalikke jõupingutusi, et kavandada, programmeerida ja rakendada midagi, mis vastab mitmele kriteeriumile:

• võimaldab teil kiiresti jõuda rakenduse struktuurini
• võimaldab teil vabalt otsida sisu
• pakub tehnilist teavet kasutatud lahenduste kohta.
• toetab teksti vormindamist ja kood
• saab salvestada GitHubis, eelistatavalt koos lihtsa kasutuselevõtu võimalusega.

Pole ime, et dokumenteerimine on seotud suurte kuludega. Teisest küljest on meeskond kasvab, onboarding tekitab palju kulusid ja selle eest esitab tugi arendajatele pidevalt samu küsimusi. Mingil hetkel on kõigil puudu ... VuePress.

VuePress on staatilise lehe generaator, mis põhineb Vue.js raamistik, mis on suurepärane dokumentatsiooni loomiseks. Heaks näiteks võib tuua Vue.js enda dokumentatsiooni.

VuePress võimaldab teil redigeerida tekste Markdown-vormingus, kasutades Vue komponente, mis annavad lõpuks väga laiad võimalused. Alustage lihtsalt kahe käsuga:

npm install -g vuepress

vuepress dev

Vaikimisi töötab VuePress kataloogis docs / ja loob sinna oma. vuepress kausta. Pärast ülaltoodud käskude sisestamist käivitab ta automaatselt programmi Sõlme server ja kuvab dokumentatsiooni aadressil localhost: 8080 /. Siin on näide faili struktuurist.

Korraliku konfiguratsiooni korral loob VuePress täieliku ja väga esteetilise lehe. Nagu näete ülaltoodud ekraanil, sisaldab meie dokumentatsioon kaks kohandatud komponenti - CodeHeading ja ColorSample.

Lihtsam näide alguseks on CodeHeading.

CodeHeading.vue

Mall:

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

Stiilid:

.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 {
   background-color: #cc0000;

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

 &__hea {
   background-color: #3eaf7c;

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

 &__default {
   background-color: #4e6e8e;
 }
}

Stsenaarium:

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

See on Vue.js komponendi standardne süntaks, mis on kergesti kättesaadav Markdown-failides. Siin on näide rakendusest (/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');

Nii oleme saanud täiesti loetava lahenduse koodiga töötamise näidete esitamiseks.

Probably every frontend developer has had a situation where they lacked the HEX representation of any colour from the graphics design. And what if you could always have colour at hand and fix a certain palette in advance? That’s right – documentation somehow makes us stick to the standard. The result may look like the following:

Selles näites kasutati komponenti ColorPicker.vue. See ei teeni mitte ainult antud värvi esitamist - klikkides ringil, kopeerime HEX-koodi automaatselt lõikelauale.

Mall:

<template>
  <div class="color-sample">
    <div class="color-sample__container">
      <div
        class="color-sample__circle"
        @click="copyToClipboard"
        :style="`background-color: ${ color }`"
        title="Klõpsake HEX-koodi kopeerimiseks"
      >
        <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>(( nimi ))</strong><br/>
        ((värv))
      </p>
    </div>
  </div>
</template>

Stiilid:

.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: absoluutne;
   top: 0;
   left: 0;
   right: 0;
   bottom: 0;
   taustavärv: valge;
   text-align: center;
 }
}

Stsenaarium:

eksportida vaikimisi {
 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");
   }
 }
};

Näide rakendusest (/docs/Design/colors.md):

Tähelepanu tasub pöörata VuePressi sisseehitatud otsingumootorile:

Markdown-failide pealkirjade põhjal töötab see automaatselt. Sel viisil tehtud dokumentatsiooni konfiguratsioon tuleb järgmine:

module.exports = {
 title: 'Dokumendid',
 themeConfig: {
   sidebar: [
     {
       title: 'Üldine',
       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: 'Teadmised',
       items: [
         { text: 'VueSchools', link: 'https://vueschool.io/' }
       ]
     },
     {
       text: 'Codest',
       link: 'https://codesthq.com'
     },
     {
       text: 'Dokumendid GitHubis',
       link: 'https://github.com/'
     }
   ]
 }
}

Koos vuepress ehitada käsuga saame kohe genereerida staatilisi HTML-faile, mis on valmis kiireks avaldamiseks koos täieliku varade toetusega.

Väärib märkimist, et VuePress võimaldab automaatset kasutuselevõttu erinevatel platvormidel, sealhulgas GitHubi lehekülgedel. Lisaks teeb VuePressi üsna heaks blogilahenduseks võimalus luua oma teemasid.

Kui ülaltoodud näited äratasid teie uudishimu, siis lisateabe saamiseks soovitan tutvuda VuePressi ametliku dokumentatsiooniga. projekt.

Loe edasi:

• Koodi optimeerimine päringuobjektide abil
• Vue.js põhitõed. Kuidas selle raamistikuga alustada?
• Turvalisus Javascript pakettides
• GraphQL: tootmises saadud õppetunnid