spm使用之八谈谈spm doc watch的调用过程

在自己开发的seajs模块目录里执行spm doc watch，将会启动一个http服务和启动实时监控docs目录文件夹里md 文件以及一些html，css，js文件被修改后的变化， 这些变化，将会复制到_site目录里，以便F5刷新看到的是新修改的页面内容。

spm doc watch执行后，将会调用nico，这个可以看spm doc的源码，然后会调用到 nico\lib\engines\_env.js, 这种前面带个下划线的_env.js 具体还隐含了什么意思我目前还不知道, 以后懂了再另外写东西.

这个_env.js文件里有个option, 很明显, nico执行的时候, 从里面获取了一些参数.

因为我这个是在 D:\Projects\examples-master\sea-modules\examples\tanchu 这个模块里执行的spm doc watch命令,

我用console.log打印了option

{ _cache:
   { commanderArgs: [],
     package:
      { family: 'mylib',
        name: 'tanchu',
        version: '1.0.0',
        description: 'the tanchu',
        homepage: 'https://github.com/Administrator/tanchu',
        author: 'encorehu',
        maintainers: [Object],
        repository: [Object],
        bugs: [Object],
        keywords: [],
        licenses: 'MIT',
        spm: [Object] },
     theme: 'C:\\Documents and Settings\\Administrator\\.spm\\themes\\cmd',
     permalink: '{{directory}}/{{filename}}.html',
     ignorefilter: [Function],
     writers:
      [ 'nico.PageWriter',
        'nico.StaticWriter',
        'nico.FileWriter',
        'nico.MochaWriter' ],
     assets_host: 'http://assets.spmjs.org',
     filters:
      { debug: [Function],
        debug_file: [Function],
        find: [Function],
        find_category: [Function: findCategory],
        replace_code: [Function],
        clean_alias: [Function],
        css_alias: [Function],
        render_src: [Function],
        is_runtime_handlebars: [Function],
        is_plugin_text: [Function],
        add_anchor: [Function],
        gitRepoUrl: [Function],
        fixlink: [Function],
        fixIssues: [Function],
        getNickName: [Function] },
     isCssModule: false,
     sourcedir: 'D:\\Projects\\examples-master\\sea-modules\\examples\\tanchu',
     outputdir: 'D:\\Projects\\examples-master\\sea-modules\\examples\\tanchu\\_
site',
     functions:
      { dist_files: [Function],
        src_files: [Function],
        spec_files: [Function],
        engines: [Function] },
     reader: [Function],
     globals: { theme: [Object], system: [Object] },
     iframeId: 'index',
     __rebuild: true,
     cachetag: '0.2.0',
     encoding: 'utf8',
     tocLevel: 3,
     engine: 'swig',
     ignoredotfiles: true },
  Option: [Function: Option],
  defaults: [Function] }

可以看出, 这里有一些 nico需要的配置信息, 实际上, 我最关注的是一个叫做theme的字段, 这里theme:'C:\\Documents and Settings\\Administrator\\.spm\\themes\\cmd',可以看到 执行spm doc watch的时候, 默认调用了C:\Documents and Settings\Administrator\.spm\themes\cmd 这个文档模板

前面我尝试过使用别的文档主题模板, 结果装好后需要自己去修改 spm-doc文件夹里的index.js文件, 跟踪到这里, 我又把index.js修改成原样了(因为修改index.js后, 相当于修改了全局, 以后不带--theme参数的话, 就会用你修改后的那个主题目录了). 所以还是不去硬性修改spm doc里的文件.

看到上面的配置信息,我自己又另外查看了nico的启动参数, 我发现应该是可以指定 theme的. 就是使用 --theme 即可.下面做个尝试

D:\Projects\examples-master\sea-modules\examples\tanchu>spm doc watch --theme cmd
           nico: 0.4.7
           load: C:/Documents and Settings/Administrator/.spm/themes/cmd/nico.js

           load: PageWriter
           load: StaticWriter
           load: FileWriter
           load: fail to load nico.MochaWriter
            run: PageWriter
          write: 3 pages
{ _cache:
   { commanderArgs: [],
     package:
      { family: 'mylib',
        name: 'tanchu',
        ... },
     theme: 'cmd',
     permalink: '{{directory}}/{{filename}}.html',
     ignorefilter: [Function],
     ... }
       template: cmd\templates has no templates available //这里报错了, 这个报错信息我修改过.C:\Documents and Settings\Administrator\Application Data\npm\node_modules\spm-doc\node_modules\nico\lib\engines\_env.js(33):     log.warn('template', 'no templates available');

C:\Documents and Settings\Administrator\Application Data\npm\node_modules\spm-do
c\node_modules\nico\node_modules\swig\lib\swig.js:169
      throw excp;
            ^
undefined

报错, 最开始我以为只要指定 --theme cmd 就行, 就是说指定theme的名字即可, 后来我看到错误了, 我知道, 这个--theme 指定的参数, 应该是theme的路径, 就是 static和templates目录的上级目录即可, 也就是上面的C:\Documents and Settings\Administrator\.spm\themes\cmd 

好了, 那就按照 --theme <theme_path> 这样的方式输入命令吧:

D:\Projects\examples-master\sea-modules\examples\tanchu>spm doc watch --theme C:\Documents and Settings\Administrator\.spm\themes\cmd
           nico: 0.4.7
           load: C:/Documents and Settings/Administrator/.spm/themes/cmd/nico.js

           load: PageWriter
           load: StaticWriter
           load: FileWriter
           load: fail to load nico.MochaWriter
            run: PageWriter
          write: 3 pages
{ _cache:
   { commanderArgs: [ 'and', 'Settings\\Administrator\\.spm\\themes\\cmd' ],
     package:
      { ... },
     theme: 'C:\\Documents',
     permalink: '{{directory}}/{{filename}}.html',
     ... }
       template: C:\Documents\templates has no templates available

C:\Documents and Settings\Administrator\Application Data\npm\node_modules\spm-do
c\node_modules\nico\node_modules\swig\lib\swig.js:169
      throw excp;
            ^
undefined

可以发现, 最后theme得到的路径居然是 C:\Documents, 事实上是将C:\Documents and Settings\Administrator\.spm\themes\cmd 从空格处截断了, 结合windows上面执行其他dos命令也会出现这种情况, 我立马就知道, 应该使用双引号将带有空格的路径包括起来, 也就是这个命令了:

D:\Projects\examples-master\sea-modules\examples\tanchu>spm doc watch --theme "C:\Documents and Settings\Administrator\.spm\themes\cmd"

果然, 问题解决了, 指定theme 路径, 使用双引号括起来, 问题消失. 

然后再试试别的路径, 换成我自己修改的pure吧.

嗯, 结果一样正常出现了:

D:\Projects\examples-master\sea-modules\examples\tanchu>spm doc watch --theme "C:\Documents and Settings\Administrator\.spm\themes\pure"

           nico: 0.4.7
           load: C:/Documents and Settings/Administrator/.spm/themes/cmd/nico.js

           load: PageWriter
           load: StaticWriter
           load: FileWriter
           load: MochaWriter
            run: PageWriter
          write: 3 pages
{ _cache:
   { commanderArgs: [],
     package:
      { ...},
     theme: 'C:\\Documents and Settings\\Administrator\\.spm\\themes\\pure',
     ... ,
     isCssModule: false,
     sourcedir: 'D:\\Projects\\examples-master\\sea-modules\\examples\\tanchu',
     outputdir: 'D:\\Projects\\examples-master\\sea-modules\\examples\\tanchu\\_site',
     ... 
            run: StaticWriter
           copy: C:/Documents and Settings/Administrator/.spm/themes/pure/static
 -> _site/static
            run: FileWriter
            run: MochaWriter
           time: 0.994s
          watch: D:\Projects\examples-master\sea-modules\examples\tanchu   //spm doc 监视这俩目录
          watch: C:\Documents and Settings\Administrator\.spm\themes\pure  //spm doc 监视这俩目录

         server: http://127.0.0.1:8000
         change: _site

以前我准备给 spm doc watch加个--themename的参数的, 现在我发现它最后调用了 nico, 而nico又能够接受 --theme参数, theme是主题的绝对路径, 我就放弃了这个想法了.

function getThemePath(themeName) {
  //console.log(themeName);
  if( themeName='undefined'){
    themeName='cmd'
  }
  return path.join(
    spmrc.get('user.home'),
    '.spm/themes/'+themeName+'/nico.js'
  );
}

这个index.js, 后来都该回原版了, 因为我觉得没必要了, 可能唯一的麻烦就是需要输入 theme的绝对路径.

总而言之, 我对这个流程只研究了怎么多, spm doc watch最后调用了nico的server功能, 使用nico自带的替换功能, 将templates里的html 进行了一部分替换, 最后输出到网页里.

其他的流程, 请各位自己研究, 捡自己感兴趣的看看就行, 我们的重点应该是应用和改善spm doc watch.