Contributing to the IntelliJ Platform SDK

本文档描述了我们对开源IntelliJ Platform SDK文档和示例代码的贡献指南. 在开始向SDK提供内容之前,请仔细阅读本页以及行为准则和许可证文档. 有关为IntelliJ平台本身做出贡献的信息,请访问贡献IntelliJ平台.

在创作SDK内容和提交Pull请求之前,请先了解一些有用的信息.

• 虚拟列表项

设置文档构建环境

该站点通过Jekyll运行,这是一个流行的静态站点生成器,用Ruby编写.它可以在本地托管,以确保任何更改都是正确的.设置完成后,运行网站就像调用“rake preview”一样简单.

或者,该站点也可以托管在Docker容器中.在Mac和Windows上,这意味着该站点托管在虚拟机中. Docker维护这个容器,根据Dockerfile中的指令构建它.构建映像时会自动安装所有依赖项(Ruby等),从而减少了手动配置步骤. Docker镜像也用于构建已发布网站,因此它是一个已知的工作环境.

使用Docker开发文档

请按照以下步骤使用Docker:

• 首先,使用Docker Toolbox安装Docker.
• 在Windows和Mac上,启动Docker主机虚拟机(启动“Docker Quickstart终端”或运行“Kitematic”.有关更多信息,请参阅[docker.com]上的入门指南(https://www.docker.com) 细节).
• 将intellij-sdk-docsrepo克隆到本地机器,并初始化sdkdocs-template子模块.
• 将当前目录更改为git仓库的父目录.
• 运行docker build -t intellij-sdk-docs .从当前文件夹构建docker镜像,并为其指定标签intellij-sdk-docs.  
• 请注意,这必须从设置了各种DOCKER_ *环境变量的命令提示符运行,例如Docker Quickstart Terminal.
• 运行docker run -p 4000:4000 -v $ PWD:/usr/src/app intellij-sdk-docs. 该命令将:   
• 启动名为intellij-sdk-docs的docker容器.   
• 将Docker容器中的端口4000转发到docker客户端上的端口4000.

在本地开发文档

要构建文档站点,您需要:

• Ruby 2 - Jekyll是一个Ruby应用程序.

• Ruby 2 DevKit(适用于Windows) - 需要编译一些Jekyll的依赖项,并且需要安装DevKit.

*gem install bundler - 该站点使用Bundler来管理repo中的gem依赖项,而不是全局安装到本地操作系统. 运行此命令以全局安装Bundler工具集.

苹果系统

macOS已经安装了Ruby. 所需的唯一步骤是:

*gem install bundler

Windows

*安装Ruby 2和Ruby 2 DevKit(其中一个宝石需要构建本机组件)      *安装DevKit后,请确保编辑config.yml文件以指向Ruby安装

如果您使用Chocolatey(Windows的包管理器),则此安装更容易:

• choco install ruby​​
• choco install ruby​​2.devkit
  • 安装DevKit后,请确保编辑config.yml文件以指向Ruby安装.
  • 默认情况下,这是C:\tools\DevKit\config.yml
  • 添加行- C:\tools\ruby21(包括前导减号)

引导文档构建环境

1. 确保已安装Bundler - gem install bundler.
2. 在Windows上,确保已在当前命令提示符下运行devkitvars.bat文件(例如c:\tools\DevKit\devkitvars.bat).
3. 克隆文档站点.
4. 初始化并更新sdkdocs-template子模块 - git submodule init和git submodule update
5. rake bootstrap - 这使用Bundler下载所有必需的宝石.
6. rake preview - 这将构建网站,并将其托管在本地网络服务器中.

构建和预览网站

要构建和测试网站,请运行rake preview.这将使用提供的配置构建站点并托管它.托管站点的URL显示在屏幕上,取决于_config.yml中定义的baseurl字段.

Documentation Repository Submodules

sdkdocs-template目录实际上是一个Git子模块,它包含一个私有webhelp-template存储库的子模块. sdkdocs-template存储库包含构建脚本以及允许站点运行的编译和缩小的JS和CSS. 私有的webhelp-template存储库包含构建JS和CSS的代码. 它目前是封闭源,但计划是在某些时候使它成为开源,在这种情况下,很可能会合并两个存储库.

克隆后,需要初始化和更新子模块:

初始化创建一个.gitmodules文件,在sdkdocs-template文件夹中注册一个子模块并检出文件. 请注意,当repo作为子模块添加时,它不会获得.git文件夹,而是获取指向.git文件夹的实际位置的.git文件.

子模块可以使用常规git命令更新,例如git pull. 它可以使用git checkout切换到不同的分支,并且需要使用git命令将当前检出的修订版本的任何更改提交回主存储库. 子模块最初是在特定版本中克隆的,而不是branch.update的一部分

如果对子模块进行了更改,则应在分支上创建克隆,并发送Pull请求. 可以进行更改并提交,托管存储库需要提交指向子模块当前版本的指针.

如果sdkdocs-template有任何问题,请提出问题.

创建IntelliJ Platform SDK内容

欢迎提供对IntelliJ Platform SDK的内容贡献.

请从GitHub下载或克隆开源SDK项目,进行添加或更改,并提交拉取请求.

在创建或更改内容之前,请参阅以下指南:

• SDK文档样式指南.    本指南根据Markdown语法描述了文档约定.    始终使用站点的预览测试文档更改.

• SDK代码示例指南.    本文档中描述了代码示例组织,项目设置和命名约定的约定.    始终通过构建和测试SDK代码示例来测试代码更改.