180 Documentation

目标

  • 将原始 GPars 文档从 mark-down 语法转换为 Asciidoctor

  • 创建新的外观

  • 将各种 GPars 信息（指南、参考、教程等）组合到一个位置

  • 重新排列 gpars.github.io 中的文件夹结构并停止使用 Jekyll

  • 保持网站的静态特性；只需要少量动态部分，但随着功能的增长，以后会需要更多

对于我们的文档，我们使用 Asciidoctor 工具和 Asciidoctor 的 Gradle 插件

对于托管，此实现使用 CloudFoundry PaaS 提供商，例如 IBM BlueMix、Pivotal、CloudBees、Anynines.com

简介

假设您了解 Gradle、GitHub 以及静态和动态 Web servlet，并且熟悉网站文件夹结构、html 等。

我们使用名为 Gradle 的基于 Groovy 的构建工具来构建此网站。几个不同的构建脚本用于实现此网站。每个脚本都是纯文本 UTF-8 编码。每个脚本都有不同的用途。

原始的 GPars 文档使用 mark-down 语法存储为文本文件。这些文件已被转换为更强大的 Asciidoctor 语法。每个文本文件都是纯文本 UTF-8 编码，位于 ./Website/src/docs/asciidoc 文件夹以及每个主题的子文件夹中。

所有转换后的文件都保留原始的 markdown 文件名，但现在带有 .adoc 后缀。

divider

Gradle 构建工具概述

Gradle 组件

root folder layout

此构建工具允许我们包含一个包含 Gradle 使用的组件的 *wrapper*。

克隆此存储库后，即使您的系统上未安装 Gradle，这些组件也是构建和管理此应用程序所需的全部内容。这避免了在您的系统上安装 Gradle。

下载的 Wrapper 中的 Gradle 工具 -

  1. gradlew - 用于执行构建工具的 Linux/Apple bash wrapper 脚本

  2. gradlew.bat - 上述脚本的 Windows 版本

  3. gradle/ - 构建工具组件的文件夹

  4. gradle.properties - 影响此构建工具执行的设置

Gradle 构建脚本

  1. build.gradle - 执行 defaultTasks 来设置作业，运行 Asciidoctor 任务，然后构建 servlet war 文件。

  2. gretty.gradle - 用于内部目的，将此站点作为本地 Web 服务运行；用于在上传到服务器之前检查更改；在命令行中，执行以下操作
    cd ./Website
    ./gradlew -b gretty.gradle appRun
    然后在浏览器地址栏中使用：https://127.0.0.1:8080 - 注意：可能无法在 Java JVM9 上运行

  3. deploy.gradle - 将我们的 servlet war 文件上传到目标 CloudFoundry（或 jetty 或 tomcat）服务；有关更多详细信息，请参阅此脚本中的注释；注意：首次使用前输入凭据；要运行此脚本，请尝试
    cd ./Website
    ./gradlew -b deploy.gradle
    此脚本中的默认任务会运行几个步骤来登录到远程 CloudFoundry API，并将现有的 .war 文件推送到其中。此脚本将 build.gradle 脚本从 ./build/libs 文件夹构建的 .war 文件发布到目标。

divider

根文件夹布局

网站根目录和子文件夹的输入/输出文件夹指定 - 请参阅 build.gradle
asciidoctor {
    sourceDir = file('src/docs/asciidoc') (1)
    outputDir = file('src/main/webapp')   (2)
}
1 声明所有 *.adoc 文件的根输入文件夹
2 声明生成的 HTML 文档的输出文件夹

输入源

对于输入，Asciidoctor 读取 ./Website/src/docs/asciidoc 文件夹及其任何子文件夹中的每个 *.adoc 文件。

root folder layout

输入子文件夹布局

主题讨论领域通常被分解成几部分，通常以文件夹中的文件夹（即子文件夹）的形式进行物理隔离。

我们的网站遵循这种模式。以下是截至 2015 年 12 月我们当前输入子文件夹及其用途的列表。请注意，以后可能会添加其他子文件夹。

  1. archive - 不再需要的原始资料，但为了“以防万一”而保存

  2. asciidoc - 包含转换为 .adoc 文件的 markdown 文档以及按主题分类的子文件夹

  3. css - 样式组件；

  4. images - 各种资料，一些是当前的，一些是过时的，需要清理

  5. markdown - 从 github 存储库保存的原始 markdown 文件 - 保留还是删除？目前没有坏处

  6. resources - 用于旧版本的 zip 文件

  7. txt - 搜索过时/失效 URL 的副产品

divider

HTML 生成过程

HTML 生成由 build.gradle 脚本中的单个任务提供。Asciidoctor 任务拥有此权限。

所有文档文件都保留其原始的 *mark-down* 文件名以及 .adoc 后缀。

build.gradle 中的 Asciidoctor 插件从 ./Website/src/docs/asciidoc 文件夹读取每个 .adoc 文件。它呈现一个等效的 .html 文件，并将其写入 ./Website/src/main/webapp 文件夹或子文件夹。

保留源文件夹的文件夹结构。

根 HTML 生成命令

  • 手动 - 从命令行手动运行 build.gradle 中的单个任务时，执行以下操作
    cd ./Website
    ./gradlew asciidoctor

  • 自动 - 运行此脚本中声明为默认任务的任务。它们是 'clean','asciidoctor', 'build', 'war'。
    在 gradlew 后不带任何任务名称即可执行此操作
    cd ./Website
    ./gradlew

divider

PDF 生成脚本

PDF 生成由相同的 gradle 脚本提供。它们之间的唯一区别是输入和输出文件夹的声明。它们出现在每个脚本的第 50-55 行附近。它们类似于以下逻辑，该逻辑为每个 *.adoc 文件在我们的 core 文件夹中生成一个 PDF 文档

Core PDF 的示例输入/输出文件夹指定
sourceDir = file('src/docs/asciidoc/core')        (1)
outputDir = file('src/main/webapp/core')    (2)
1 声明 *.adoc 文件的输入文件夹
2 声明生成的 PDF 的输出文件夹
PDF 脚本列表

  1. pdf.gradle - 为 index.adoc 中定义的完整用户指南生成单页 PDF；此索引使用 include 语法插入 *.txt 文件中的文本片段。

  2. pdfcore.gradle - 为每个以 .adoc 结尾的 ./core 主题文件生成单页 PDF

  3. pdfreference.gradle - 为 index.adoc 中定义的参考手册生成单页 PDF；此索引使用 include 语法插入 *.txt 文件中的文本片段。

  4. pdfstructure.gradle - 生成一个单页 PDF，描述此网站的工作原理、其文件夹、脚本等。

divider

root folder layout

输出生成

./Website/src/main/webapp 文件夹用作我们网站的输出捕获文件夹。Asciidoctor 将 .html（或 .PDF）输出写入此处。如有必要，将复制子文件夹以保留源的完整性。

输出子文件夹布局

主题讨论领域通常被分解成几部分，通常以文件夹中的文件夹（即子文件夹）的形式进行物理隔离。

我们的网站遵循这种模式。以下是截至 2015 年 12 月我们当前输出子文件夹及其用途的列表。请注意，以后可能会添加其他子文件夹。

  1. api - 从最新版本复制的 groovydoc 和 javadoc 编译器输出；groovy-overview-summary.html 和 java-overview-summary.html 由 build.gradle 逻辑重新构建。

  2. core - 描述 GPars 的主要机制。

  3. css - 样式组件；css3menu1 子目录用于站点导航栏。

  4. font-awesome - 供 asciidoctor 生成 admonition 图标。

  5. fonts - Asciidoctor 使用。

  6. guide - 构建我们的 .html 用户指南和配套 .pdf 的所有内容。

  7. images - 各种资料，一些是当前的，一些是过时的，需要清理

  8. img - 用于登录页面（index.html）。

  9. JonKerridgeBook - 来自他的资料和 PDF 系列的章节。

  10. js - 用于登录页面和 JQuery 支持。

  11. quickstart - .html 及其单页 PDF 版本的简短参考手册。

divider
我们的登录页面 index.html 不是 Asciidoctor 工件，不得丢失或删除。
divider

root folder layout

WEB-INF 审核

WEB-INF 是我们用于 java servlet 的部署文件夹。它包含传统的支持和配置文件。

以下是截至 2015 年 12 月的组件、子文件夹及其用途的列表。

  1. groovy - 以 groovy 脚本编写的动态组件（以及许多过时的内容）。

  2. includes - 存储为 groovy 模板的 html 片段，用于 include 目标。

  3. lib - 支持的运行时逻辑的 jar 包。
    1) caelyf-1.3.3.jar 中的附加 servlet 处理，以及
    2) 在 Doctor-all-1.0.jar 中将任何 *.adoc 文件实时通过 Asciidoctor 转换为 servlet 响应流。

  4. pages - groovy 模板（.gtpl）向 servlet 响应添加更多文本。

  5. logging.properties - 根据需要调整日志级别。

  6. routes.groovy - 为浏览器地址向我们自己的代码添加其他映射。例如
    get "/datetime",forward:"/datetime.groovy", cache:2.minutes
    其中 get、post 等 HTTP 请求会转到特定的 groovy 脚本；如果 Redis 服务正在运行，则在重新构建响应之前，响应会被复制到缓存中 2 分钟。

    在此示例中，来自浏览器地址 https://127.0.0.1:8080/datetime 的请求将转发到 /Website/src/main/webapp/WEB-INF/groovy 文件夹中的 datetime.groovy 脚本。它获取系统日期，然后将请求转发到 /Website/src/main/webapp/WEB-INF/pages 中的模板以进行最终响应解析。

  7. web.xml - 通过将文件后缀映射到 servlet 来配置 servlet 容器（jetty、tomcat 等）；很少更改。

divider

示例工作流程

即将添加
divider