Hologram 使用教程

1. 项目目录结构及介绍

Hologram 是一个 Ruby gem，用于解析 CSS 中的注释并将其转换成美观的风格指南。项目的目录结构大致如下：

hologram/
├── bin/              # 存放命令行工具相关脚本
├── lib/              # gem 的核心库代码
├── spec/             # 单元测试和集成测试代码
├── .gitignore        # 指定 Git 忽略的文件和目录
├── .travis.yml       # Travis CI 持续集成配置文件
├── CHANGELOG.md      # 项目更新日志
├── Gemfile           # Ruby 项目依赖文件
├── LICENSE.txt       # 项目许可证文件
├── README.md         # 项目说明文件
├── Rakefile          # Rake 任务配置文件
├── example_markdown_renderer.rb.example # 示例 Markdown 渲染器
└── hologram.gemspec   # gem 的配置文件

2. 项目的启动文件介绍

Hologram 的启动主要是通过命令行工具进行的。在项目的 bin/ 目录下，你可以找到 hologram 脚本，这是运行 gem 的主要方式。

启动 hologram 的基本命令如下：

hologram

此外，还有一些命令行参数可以使用，例如：

• -c 或 --config：指定配置文件，默认 hologram 会查找 hologram_config.yml。

3. 项目的配置文件介绍

Hologram 需要一个 YAML 格式的配置文件来设置一些基本参数。配置文件通常命名为 hologram_config.yml，位于项目的根目录。

以下是一个示例配置文件的内容：

source: ./sass
destination: ./docs
documentation_assets: ./docs_assets
code_example_templates: ./templates
code_example_renderers: ./renderers
custom_markdown: markdown_renderer.rb
index: getting-started
dependencies:
  - ./ vendor Assets
ignore_paths:
  - "./node_modules"
nav_level: section
exit_on_warnings: false

配置文件中可以设置的参数包括：

• source：指定源文件所在的目录，Hologram 会递归地解析这些文件中的注释。
• destination：指定生成的文档存放的目录。
• documentation_assets：包含文档所需的支持资产，如 HTML 片段、CSS、JavaScript 和图片等。
• code_example_templates：代码示例模板的目录。
• code_example_renderers：自定义代码渲染器的目录。
• custom_markdown：自定义 Markdown 渲染器的文件名。
• index：指定作为索引页面的分类。
• dependencies：文档输出目录中需要包含的依赖文件夹列表。
• ignore_paths：指定要忽略的文件或目录模式。
• nav_level：设置导航级别的显示。
• exit_on_warnings：是否在出现警告时退出程序。

确保在开始使用 Hologram 前，正确配置这些参数以符合你的项目需求。