Dokumentaation kirjoittaminen on tullut helpoksi VuePressin ansiosta.

On aina ollut tärkeää pyrkiä suunnittelemaan, ohjelmoimaan ja toteuttamaan jotakin, joka täyttää useita kriteerejä:

• avulla pääset nopeasti sovelluksen rakenteeseen.
• voit vapaasti etsiä sisältöä
• tarjoaa teknisiä tietoja käytetyistä ratkaisuista.
• tukee tekstin muotoilua ja koodi
• voidaan tallentaa GitHubiin, mieluiten niin, että se voidaan ottaa helposti käyttöön.

Ei ihme, että dokumentointiin liittyy suuria kuluja. Toisaalta joukkue kasvaa, palveluun ottaminen aiheuttaa paljon kustannuksia, ja sen vuoksi tuki esittää kehittäjille jatkuvasti samoja kysymyksiä. Jossain vaiheessa kaikki kaipaavat ... VuePress.

VuePress on staattinen sivugeneraattori, joka perustuu Vue.js-kehys, joka on erinomainen dokumentaation luomiseen. Hyvänä esimerkkinä voidaan pitää itse Vue.js:n dokumentaatiota.

VuePressin avulla voit muokata Markdown-muotoisia tekstejä Vue-komponenttien avulla, jotka tarjoavat todella monipuoliset mahdollisuudet. Aloita vain kahdella komennolla:

npm install -g vuepress

vuepress dev

Oletusarvoisesti VuePress toimii docs / -hakemistossa ja luo siihen oman. vuepress-kansion. Kun olet syöttänyt edellä mainitut komennot, se käynnistää automaattisesti ohjelman Solmu palvelin ja näyttää dokumentaation osoitteessa localhost: 8080 /. Tässä on esimerkki tiedostorakenteesta.

Oikealla kokoonpanolla VuePress luo täydellisen ja erittäin esteettisen sivun. Kuten yllä olevasta näytöstä näet, dokumentaatiomme sisältää kaksi mukautettua komponenttia - CodeHeading ja ColorSample.

Yksinkertaisempi esimerkki alussa on CodeHeading.

CodeHeading.vue

Malli:

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

Tyylit:

.code-otsikko {
 width: 100%;
 height: 40px;
 rivikorkeus: 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;
 väri: valkoinen;

 &__paha {
   background-color: #cc0000;

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

 &__good { __good {
   background-color: #3eaf7c;

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

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

Käsikirjoitus:

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

Tämä on Vue.js-komponentin vakiosyntaksi, joka on helposti saatavilla Markdown-tiedostoissa. Tässä on esimerkki toteutuksesta (/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');

Näin olemme saaneet täysin luettavan ratkaisun esimerkkien esittämiseen koodin kanssa työskentelystä.

Luultavasti jokaisella frontend-kehittäjällä on ollut tilanne, jossa heiltä puuttui jonkin värin HEX-edustus grafiikkasuunnittelusta. Entä jos sinulla olisi aina väri käsillä ja voisit korjata tietyn paletin etukäteen? Aivan oikein - dokumentaatio saa meidät jotenkin pitämään kiinni standardista. Tulos voi näyttää seuraavalta:

Tässä esimerkissä käytettiin ColorPicker.vue-komponenttia. Se palvelee paitsi tietyn värin esittämistä - klikkaamalla ympyrää kopioimme HEX-koodin automaattisesti leikepöydälle.

Malli:

<template>
  <div class="color-sample">
    <div class="color-sample__container">
      <div
        class="color-sample__circle"
        @click="copyToClipboard"
        :style="`background-color: ${ color }`"
        title="Kopioi HEX-koodi napsauttamalla sitä"
      >
        <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äri ))
      </p>
    </div>
  </div>
</template>

Tyylit:

.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;
   taustaväri: valkoinen;
   text-align: center;
 }
}

Käsikirjoitus:

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

Esimerkki toteutuksesta (/docs/Design/colors.md):

Kannattaa kiinnittää huomiota VuePressiin rakennettuun hakukoneeseen:

Se toimii automaattisesti Markdown-tiedostojen otsikoiden perusteella. Tällä tavalla tehty dokumentaation konfigurointi on seuraava:

module.exports = {
 title: 'Docs',
 themeConfig: {
   sidebar: [
     {
       title: 'Yleistä',
       collapsable: false,
       children: [
         'General/introduction.md',
         'General/installation.md'
       ]
     },
     {
       title: 'Suunnittelu',
       collapsable: false,
       children: [
         'Design/colors.md',
         'Design/fonts.md',
         'Design/forms.md',
         'Design/layout.md'
       ]
     },
     {
       title: 'Koodi',
       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: 'Tieto',
       items: [
         { text: "VueSchools", link: 'https://vueschool.io/' }
       ]
     },
     {
       text: 'Codest',
       link: 'https://codesthq.com'
     },
     {
       text: 'Docs on GitHub',
       link: 'https://github.com/'
     }
   ]
 }
}

Kun vuepress rakentaa komennon avulla voimme luoda välittömästi staattisia HTML-tiedostoja, jotka ovat valmiita nopeaan julkaisuun täydellä asset-tuella.

On syytä mainita, että VuePress mahdollistaa automaattisen käyttöönoton eri alustoilla, kuten GitHub-sivuilla. Lisäksi mahdollisuus luoda omia teemoja tekee VuePressistä varsin hyvän blogiratkaisun.

Jos edellä mainitut esimerkit herättivät uteliaisuutesi, lisätietoja varten suosittelen tutustumaan VuePressin viralliseen dokumentaatioon. projekti.

Lue lisää:

• Koodin optimointi kyselyobjektien avulla
• Vue.js:n perusteet. Miten aloittaa tämän kehyksen kanssa?
• Turvallisuus Javascript-paketeissa
• GraphQL: tuotannossa opittua