跳到主要内容

记录Sass代码的简便方法

CSS变得越来越复杂。 Sass解决了很多CSS问题,但同时也可能给游戏带来一些额外的复杂性。记录Sass代码与记录常规CSS一样重要,如果不是这样的话。它不仅对下一个开发人员很重要,而且从现在开始六个月后你仍然可以理解自己的代码。

SassDoc是Sass JSDoc对JavaScript的要求。这个想法很简单:通过以特定方式编写内联注释来记录代码,运行一些简短的命令行代码,然后神奇地生成一些漂亮的文档。不是很好吗?

Pascal Duez,ValérianGalliat,Fabrice Weinberg和我一直致力于这个项目,我们对目前为止提出的建议感到高兴。我们的首要任务之一是保持SassDoc的可扩展性,以便它可以用于任何Sass项目。小网站?没问题。庞大的代码库?我们让你满意。

如果您对我们提供的开箱即用产品不满意,请不要担心 - SassDoc完全可扩展且可以使用。 Guardian Style Sheets(Guss),Bourbon和Neat已经跳入并将他们的文档移到了SassDoc,那你还等什么呢?

SassDoc驱动的文档在几个阶段进行 - 大多数阶段对最终用户(您)是不可见的:

  • 解析器遍历源文件夹中的所有文件以获取符合SassDoc的注释
  • 解析器构建数据树
  • 同时,(重新)生成目标文件夹
  • 如果要求,数据树会得到增强,以提供其他功能(项目之间的交叉引用,Markdown描述,订购等)
  • 数据结构被移交给主题
  • 主题将其显示在目标文件夹中
  • 你和独角兽一样快乐

内联评论

SassDoc入门就像在Sass文件中编写注释一样简单。现在,SassDoc能够使用内联注释记录函数,mixins,变量和占位符(///)或C风格的评论(/ ** * /)。

对于要记录的每个“项目”,以JSDoc方式编写一些注释。例如:

///网站上所有边距和间隙的基线/// @group configuration /// @access public /// @type Number $ baseline:1.5em;
///使一个块居中以使其成为一个容器/// @group helpers /// @param {Number} $ max-width  - 容器的最大宽度/// @require $ baseline /// @output'max- width','margin'和'width'@mixin center($ max-width:1170px){max-width:$ max-width;保证金:0 auto $ baseline;宽度:100%; }

为每个要记录的项目编写此类注释后,您只需在代码库中运行SassDoc。首先,安装SassDoc:

npm install sassdoc -g

然后在您的代码(输入文件夹)上运行它并指定应该生成文档的位置(输出文件夹):

sassdoc / assets / scss docs

您还可以传递许多选项 - 包括配置文件(JSON或YAML)的路径--config,以便您可以自定义视图。所有可用选项均可在官方文档中找到。

主题SassDoc提供了一个默认主题,可以立即使用。它主要由可以扩展或折叠的侧边栏组成,并且位于显示所有项目的主要内容区域旁边。

因为这个主题可能是最常用的主题,所以我们添加了许多额外的功能,包括:

  • 客户端搜索引擎
  • 每个项目的“查看源”链接,指向在线存储库
  • 可扩展的侧边栏,用于管理组
  • 能够为组定义自定义名称
  • 能够仅显示公共/私有项目,以及隐藏和显示别名
  • 显示每个项目(功能,混合,占位符等)的内容的能力
  • 定义自定义图标的能力
  • 能够通过JSON文件显示有关项目的信息(例如的package.json

主题引擎

我们很清楚,SassDoc的默认主题可能不适合所有人。这就是为什么我们使SassDoc完全成为可能的原因,这要归功于我们专为SassDoc打造的功能强大的主流引擎Themeleon

构建一个主题需要一些时间,但应该很容易,特别是如果你使用我们的Yeoman主题生成器。在这种情况下,所有关于回答几个问题,添加一些你最喜欢的模板引擎(Swig,Jade,Mustache,Nunjucks ......)并将一些CSS放在首位。

如果您希望主题更高级,SassDoc还提供了一系列可供任何主题导入和使用的工具。想要用Markdown写的描述吗?我们得到了它。您想为组名提供有用的别名吗?可以使用额外的工具。您甚至可以定义自己的注释。此外,为了在您构建自己的主题时帮助您,我们创建了一个“空白”主题,其中包含许多解释如何操作的注释。

第三方集成

一旦你的主题准备好了,你就可以通过npm将它打包成世界。使用Sassdoc-主题 - *名称模式意味着其他开发人员可以通过简单地传递它来将它用于SassDoc驱动的文档- 主题来自CLI的选项(或主题来自配置文件)。 Neat和Vulcan框架已经构建了自己可以使用的主题。

如果您想在部署过程中包含SassDoc,我们已经构建了一个Grunt,Gulp和Broccoli插件。或者,您可以使用原始数据或我们的Node API - 无论您的船是什么漂浮。

例如,Grunting SassDoc可能看起来像这样:

grunt.initConfig({'sassdoc':{'default':{'src':'path / to / sass','dest':'path / to / docs'}}});

SassDoc旨在通过生成简单而强大的文档来弥合API,框架,库,制造商和开发人员之间的差距。将来,我们可能会记录更多内容,包括CSS选择器,@进口规则甚至BEM方法。

如果您碰巧构建主题,需要任何帮助或只是想分享爱情,请随时与之联系@SassDoc_在Twitter上。

话: Hugo Giraudel

Hugo Giraudel是一名设计师Teknolog.io。这篇文章首次出现在网络杂志

像这样?阅读这些!



翻译字数超限