Powrót do kategorii
Frontend
tagi
css, dokumentacja, dss, grunt-dss, sublime,

Jak stworzyć automatyczną dokumentację CSS?

Artur
Artur, 26/05/2015
dokumentacja css

Dokumentacja projektu jest narzędziem bardzo pomocnym szczególnie przy pracy zespołowej i długotrwałym rozwijaniu projektu. Tworzenie jej jest procesem żmudnym, czasochłonnym i nierzadko pomijanym. W przypadku CSS pomóc w tym zadaniu może nam DSS (Documented Style Sheet Parser) oraz Grunt.js.

Oto etapy procesu:

  1. Instalacja pluginu Grunt-DSS,
  2. Stworzenie struktury template,
  3. Tworzenie komentarzy w plikach stylów,
  4. Korzystanie z dodatku do edytora Sublime Text.

Poniżej przedstawiam rozwinięcie każdego z nich.

1. Instalacja pluginu Grunt-DSS

Zakładam, że Grunt.js jest znany. W przeciwnym wypadku polecam przeczytać wprowadzenie. Strona pluginu Grunt-DSS znajduje się pod tym adresem.

W folderze projektu, w którym znajduje się plik Grunfile.js, należy w terminalu wywołać komendę:

npm install grunt-dss --save-dev

Po prawidłowej instalacji, w Grunfile.js należy dopisać:

grunt.loadNpmTasks('grunt-dss');

oraz część konfiguracyjną pluginu. Przykład poniżej:

// DSS
dss: {
  docs: {
    files: {
      '../docs/': '../less/*.less'
    },
    options: {
      template: '../docs/template/'
    }
  }
},

W sekcji files znajduje się informacja, które pliki mają ulec parsowaniu. W moim przypadku są  to wszystkie pliki .less z katalogu less. Równie dobrze parsowaniu można poddać pliki CSS, SASS, Stylus. Katalog docs jest miejscem, w którym znajdować się będą pliki wygenerowanej dokumentacji.

W sekcji template podana jest ścieżka do pliku z szablonem, o którym mowa w pkt. 2.

Wygodnie jest dodać task dss, do wykonania przez grunt-contrib-watch przy obserwowaniu plików ze stylami:

// Watch
watch: {
  less: {
    files: ['../less/*.less'],
    tasks: ['less', 'dss']
  }
}

2. Stworzenie struktury template

Struktura template jest domyślnie zawarta w pliku index.handlebars katalogu pluginu. Osobiście plik ten zmodyfikowałem i przeniosłem do katalogu  ../docs/template/.

<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="content-type" content="text/html;charset=UTF-8" />
  <title>{{project.name}} styleguide</title> 
  <link rel="stylesheet" href="assets/js/prettify/prettify.css?v=1" type="text/css" />
  <link rel="stylesheet" href="assets/css/styles.css?v=1" type="text/css" />
  <script src="assets/js/prettify/prettify.js?v=1"></script>
</head>
<body onload="prettyPrint()"> 
  <header>
    <h1>{{project.name}} styleguide</h1>
    <p class="version">v.<strong>{{project.version}}</strong></p>
    <p class="description">{{project.description}}</p>
  </header>
  <div id="wrapper">
    <nav role="main">
      <h2>Table of Contents</h2>
      <ul>
        {{#files}}
        <li><a href="#{{file}}" data-file="{{file}}">{{file}}</a></li>
        {{/files}}
      </ul>
    </nav>

    <div class="styleguide">
      {{#files}}
      <div class="file">

        <h3 id="{{file}}">{{file}}</h3>

        {{#blocks}}

        <div class="block">

          <div class="info">
            <h4>{{name}}</h4>
            {{#if description}}
            <p class="description">{{description}}</p>
            {{/if}}

            {{#state}}
            <p class="state"><span>{{name}}</span> - {{description}}</p>
            {{/state}}
          </div>

          {{#if markup}}

          <div class="example">
            <div class="item" style="display: none;">{{{markup.example}}}</div>
            <iframe></iframe>
          </div>

          {{#state}}
          <div class="example state {{class}}">
            <div class="name">{{name}}</div>
            <div class="item" data-state="{{escaped}}" style="display: none;">{{{../markup.example}}}</div>
            <iframe></iframe>
          </div>
          {{/state}}
          <pre class="prettyprint lang-html markup">
          {{{markup.escaped}}}
          </pre>

          {{/if}}

        </div>
        {{/blocks}}

      </div>
      {{/files}}
    </div>
  </div>
<footer></footer>

<script src="assets/js/jquery-2.1.3.min.js" type="text/javascript"></script>
<script>
  $(function() {
    $("div.example > div.item").each(function() {
      var $self = $(this),
          pseudoState = $self.attr("data-state"),
          $iframe = $self.next('iframe');

      $self.children().addClass(pseudoState);

      $iframe.ready(function() {
        var markup = $self.html();

        $iframe.contents().find('head').append('<link rel="stylesheet" href="../style.css?v=1" type="text/css" />');
        $iframe.contents().find('body').css('background', 'none').append('<div class="content">' + markup + '</div>');
        setTimeout(function() {
          $iframe.height($iframe.contents().find('.content')[0].scrollHeight);
        }, 1000);
      });
    });
  });
</script>
</body>
</html>

Każdy element umieszczany jest w <iframe>, w którym deklarowane są style użyte w projekcie.

$iframe.contents().find('head').append('<link rel="stylesheet" href="../style.css?v=1" type="text/css" />');

Dzięki temu style dokumentacji nie kolidują ze stylami elementów użytych w projekcie.

3. Tworzenie komentarzy w plikach stylów

Dokumentacja generowana przez DSS jest tworzona na podstawie komentarzy w plikach stylów. Przykładowo wynikiem:

/**
* @name Btn
* @description Style for the btn class
* @state .btn-primary - btn-primary state
* @state .btn-huge - btn-huge state
* @state .btn-block - btn-block state
* @state .input-block-level-mobile - input-block-level-mobile state
* @markup
* <button class="btn" type="buton">Button</button>
*/

jest:

dss

Każda klasa ze @state jest dodawana do klas zdefiniowanych w domyślnym HTML w @markup.

4. Korzystanie z dodatku do edytora Sublime Text.

Istnieje dodatek do Sublime Text o nazwie Sublime Automatic CSS Comments. Osobiście nie znalazłem go przez Package Control, ale można zainstalować go manualnie, kopiując pobrane ze strony pluginu pliki do katalogu Packages. W zależności od używanego systemu, jego lokalizacja jest odmienna.

Sublime Automatic CSS Comments jeszcze bardziej upraszcza proces tworzenia dokumentacji. W pliku ze stylami (CSS/SASS/LESS), wystarczy wpisać:

///

a następnie nacisnąć [tab], by komentarz został utworzony automatycznie ze struktury kodu. Powstały komentarz nie za każdym razem będzie taki, jakbyśmy chcieli, ale wprowadzenie drobnych poprawek na pewno jest wydajniejsze, niż pisanie ręczne.

Podsumowanie

Moim zdaniem tworzenie dokumentacji jest pożytecznym procesem, który nierzadko bywa pomijany ze względu na ograniczenia czasowe. Dzięki DSS w połączeniu z Grunt.js proces ten w przypadku CSS można jednak w dużym stopniu przyśpieszyć i zautomatyzować.

Bibliografia

[1] http://darcyclarke.me/dev/documentinginterfaces/#landing-slide
[2] https://github.com/DSSWG/DSS

Materiały pomocniczne

DSS
Grunt.js
Grunt-DSS
grunt-contrib-watch
Sublime Automatic CSS Comments

Podobne artykuły

Hashowanie plików CSS / JS w Grunt.js

Jak przejąć kontrolę nad pamięcią podręczną przeglądarki.

Ograniczenia CSS Sprites, czyli optymalizacja z rozsądkiem

Na co zwracać uwagę budując CSS Sprites i jak nie przedobrzyć z optymalizacją.

Poznajmy się
Poznajmy się
Chcesz porozmawiać o start-upach, projektach lub programowaniu?

GOGOmedia Sp. z o.o.
ul. Klimczaka 1
02-797 Warszawa

+48 22 378 47 27
GOGOmedia
GOGOmedia
Internet Software House

Jesteśmy internetową firmą technologiczną, dostarczamy kompletne rozwiązania informatyczne z zakresu web aplikacji. Kompleksowo obsługujemy klientów z różnych sektorów biznesu w zakresie dedykowanego oprogramowania. Prowadzimy szkolenia, doradzamy, wykonujemy specjalistyczne audyty i dzielimy się zdobytą przez lata wiedzą. Dla wielu jesteśmy partnerem, który pomaga osiągać wyznaczone cele biznesowe w najbardziej optymalny sposób.

Polecamy
Polecamy
narzędzia wspierające naszą codzienną pracę
  • New Relic
  • CloudFlare
  • JIRA
  • Bamboo
  • Axure
  • Zendesk
  • Microsoft Project