grunt-styleguideを使った時のREADME.mdの置き場所

Grunt StyleDocco

StyleDoccoを使ってスタイルガイドを出力すると、index.htmlにREADME.mdの内容が反映される。
ただどの場所にあるREADME.mdを読み込むのかよくわからなかったので調べた。
(特にgrunt-styleguideを使った場合によく分からなかったので)

まずStyleDoccoのソースを読むとhttps://github.com/jacobrask/styledocco/blob/master/cli.jsというファイル内で、READMEファイルを探しているのがわかる。

    // Look for a README file.
    readme: function(cb) {
      findFile(options.basePath, /^readme\.m(ark)?d(own)?/i, function(err, file) {
        if (file != null && err == null) return read(file);
        findFile(process.cwd(), /^readme\.m(ark)?d(own)?/i, function(err, file) {
          if (err != null) file = resourcesDir + 'README.md';
          read(file);
        });
      });
      var read = function(file) {
        fs.readFile(file, 'utf8', function(err, content) {
          if (err != null) cb(err);
          cb(null, content);
        });
      };
    }

options.basePathディレクトリ以下をまず探して次にprocess.cwd()を探している。
options.basePathというのは以下のstyledoccoのUsageの "[STYLESHEET(S)]"にあたる。

styledocco [options] [STYLESHEET(S)]

process.cwd()はstyledoccoコマンドを実行したディレクトリを指す。

わかりやすく例をあげよう。
たとえば以下のようなプロジェクト構成があったとする。

my_prodject
├── README.md
├── docs
├── package.json
└── styles
    └── scss
        ├── README.md
        ├── base.scss
        └── component
            └── buttons.scss

my_prodjectディレクトリ以下で

styledocco styles/scss

というコマンドを実行した場合、
options.basePathディレクトリはmy_prodject/styles/scssディレクトリだ。
なので、my_prodject/styles/scss/README.mdがindex.htmlに反映される。
もし、my_prodject/styles/scss/以下にREADME.mdがなければ、
my_prodject/README.mdがindex.htmlに反映される。

次に、grunt-styleguideを使った場合だ。
grunt-styleguideはstyledoccoとkssの2つを指定できるが今回はもちろんstyledoccoを指定する。

ディレクトリ構成は以下にする。

my_prodject
├── Gruntfile.js
├── README.md
├── docs
├── package.json
└── styles
    └── scss
        ├── README.md
        ├── base.scss
        └── component
            └── buttons.scss

そしてGruntfile.jsの内容が以下だとする。

module.exports = function(grunt) {
	grunt.initConfig({
	  styleguide: {
            styledocco: {
                options: {
                    framework: {
                        name: 'styledocco'
                    }
                },
                files: {
                    'docs': 'styles/scss/**/*.scss'
                }
            },
          }
	});
  grunt.loadNpmTasks('grunt-styleguide');
  grunt.registerTask('default', ['styleguide']);
};

この場合も、結局は、my_prodject/styles/scss/README.md か
それがなければmy_prodject/README.mdがindex.htmlに反映されることになる。
つまり、options.basePathディレクトリにあたるディレクトリは、
filesのvalueで指定した 'styles/scss/**/*.scss'の 'styles/scss/'になる。

ではなぜそうなるかgrunt-styleguideのソースを読んでみると、
filesのvalueで指定した'styles/scss/**/*.scss'をgrunt.file.expandメソッドを使って展開し、ファイル名の配列にしている。
今回のプロジェクト構成だと、
'styles/scss/base.scss'と'styles/scss/component/buttons.scss'になる。
このファイル名たちのディレクトリを再帰的に求めている。
'styles/scss/base.scss'は、styles/scss, stylesの2つになる。
'styles/scss/component/buttons.scss'はstyles/scss/component, styles/scss, stylesの3つになる。
でこれらの共通のディレクトリを探し、その一番最初のディレクトリが採用される。
共通のディレクトリは、styles/scss, stylesで、一番最初のディレクトリはstyles/scssだ。

まあよく分からなければ、grunt-styleguideプロジェクトをcloneしてgruntを実行すれば、
自動的にテストが走りstyledoccoとkssのスタイルガイドが出力されるので、その実行をデバッグすればよいだろう。