Image for Jak stworzyć automatyczną dokumentację CSS?

Jak stworzyć automatyczną dokumentację CSS?

Czas czytania:

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: {
    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

Zainteresował Cię ten artykuł?

Oferujemy profesjonalne wsparcie programistów w technologii Web.
Może Cię również zainteresować:
Clutch Recognizes GOGOmedia as a 2022 Development Leader in Poland

GOGOmedia is a multidisciplinary team with vast experience in the digital technology space. We deliver… Read More

Zatrzymać użytkownika na stronie — 4 praktyczne sposoby

Tworząc stronę, zadaliście się sobie mnóstwo trudu. Macie dobre teksty, poprawne UX i atrakcyjny design,… Read More