Jak stworzyć automatyczną dokumentację CSS?

GOGOmedia TechBlog
Frontend
Jak stworzyć automatyczną dokumentację CSS?

Frontend

26 maja 2015

Jak stworzyć automatyczną dokumentację CSS?

Czas czytania:

GOGO.Developer

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:

Instalacja pluginu Grunt-DSS,
Stworzenie struktury template,
Tworzenie komentarzy w plikach stylów,
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: {
    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:

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ć.