文档章节

Asciidoctor 与 gradle 整合生成 PDF备忘

郁也风
 郁也风
发布于 07/25 02:18
字数 1364
阅读 176
收藏 0

缘起

简单文档一般使用 markdown 就足够了,尤其单页文档,不过稍微复杂点的文档用这玩意显然就很不方便了,就单单一个不支持 include 就很痛苦,虽然可以用 pandoc 做一些 hack 处理,不过麻烦啊,尤其还需要生成 html5pdf 的时候。

所以这时候个人倾向于使用 asciidoc 格式来写文档。

update: 为演示此功能,专门在 GitHub 上开了个项目: asciidoctor-gradle-example

配置

编译 asciidochtml5pdf 的话,Asciidoctor 提供了命令行工具,不过这玩意需要通过 gem 安装,如果额外还想生成 PDF,还需要安装 asciidoctor-pdf,看看官方文档就知道麻烦事不少。

所以还是配合 gradle 省事,一个配置文件搞定,尤其对于 java 程序员来说,gradle 应该算是标配了吧——呃,maven 用户可能有话说。

目录结构

gradle 项目的一个最基本的目录结构应该如下:

.
├── build.gradle
├── data
│   ├── fonts
│   │   ├── KaiGenGothicCN-Bold-Italic.ttf
│   │   ├── KaiGenGothicCN-Bold.ttf
│   │   ├── KaiGenGothicCN-Regular-Italic.ttf
│   │   ├── KaiGenGothicCN-Regular.ttf
│   │   ├── RobotoMono-Bold.ttf
│   │   ├── RobotoMono-BoldItalic.ttf
│   │   ├── RobotoMono-Italic.ttf
│   │   └── RobotoMono-Regular.ttf
│   └── themes
│       └── basic-theme.yml
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew
├── gradlew.bat
├── settings.gradle
└── src
    └── docs
        └── asciidoc
            ├── chapter
            │   └── 0010_overview.adoc
            ├── images
            │   └── keep
            └── spec.adoc

简单说明一下:

  • src/docs/asciidoc: asciidoc 所在目录
  • data/fonts: 用于生成 PDF 的字体文件目录
  • data/themes: 用于定义 PDF 的主题文件目录

build.gradle 配置

buildscript {
    repositories {
        maven {
            url "http://maven.aliyun.com/nexus/content/groups/public/"
        }

        jcenter()
        mavenCentral()
    }
}

plugins {
    id "org.asciidoctor.jvm.convert" version "2.3.0"
    id "org.asciidoctor.jvm.pdf" version "2.3.0"
}

wrapper {
    distributionType = Wrapper.DistributionType.ALL
}

version = '1.0.0'

asciidoctor {
    logDocuments true

    // sourceDir  file('docs')
    sources {
        include 'spec.adoc'
    }
    baseDirFollowsSourceDir()
    // outputDir  file('build/docs')

    // 强制每次都重新生成
    outputs.upToDateWhen { false }
    outputOptions {
        backends = ['html5', 'pdf']
    }

    // pdfThemes {
    //     local 'basic', {
    //         styleDir = file('data/themes/basic')
    //         styleName = 'basic'
    //     }
    // }
    attributes 'pdf-fontsdir': file('data/fonts')
    attributes 'pdf-stylesdir': file('data/themes')
    attributes 'pdf-style': 'basic'

     // 版本号
    attributes 'revnumber': project.version

    // 一些通用属性
    attributes 'toc': 'left'
    attributes 'toclevels': 4
    attributes 'toc-title': '目录'
    attributes 'docinfo1': ''
    attributes 'imagesdir': 'images'
    // 语法高亮,可选项有 coderay, highlightjs, prettify, pygments
    // 为保证生成的 html5 和 pdf 均有语法高亮,所以启用 coderay
    // 使用其它几个选项还需要做不少额外的工作,没有必要
    attributes 'source-highlighter': 'coderay'
    attributes 'sectnums': true
    attributes 'sectanchors': true
    attributes 'sectlinks': true
    attributes 'experimental': true


    // TIP、NOTE 之类的用自体图标显示
    // 之所以将此属性放置在这儿是为了避免 idea asciidoc 插件无法正常显示
    attributes 'icons': 'font'
}

重点需要注意:

  • plugins 下的两个 plugin 使用版本为 2.3.0,而官网是 2.4.0,但是后者在各个 maven 库中都没发现,估计截止当前位置尚未更新
  • asciidoctor 配置中可以不用官网文档写的 pdfThemes,也就是上面源码中注释的部分,直接采用 attributes 'pdf-fontsdir' 这种配置即可,看源码就知道,前者也不过就是为了达到后者的效果
  • source-highlighter 使用 coderay,这个相比其它源码高亮工具稍显简单,不过好处是不需额外配置就可以提供 PDF 高亮。

PDF 示例:

PDF 示例

入口 adoc 文件示例

= 开发规范

:toc: left
:toc-title: 目录
:toclevels: 3
:source-highlighter: coderay
:imagesdir: images
:icons: font
:sectnums:
:sectanchors:
:sectlinks:
:experimental:
:revnumber: v1.0

[#overview]
== 概述
include::chapter/0010_overview.adoc[]

上述文件其实把 build.gradle 中的 attributes 又定义了一遍,之所以如此是为了在 vscode、WebStorm 之类的工具中可以直接预览,当然这是可选项,如果不需要这种比较一致的预览需求,完全可以把入口 adoc 中的这些配置项删除。

PDF 中文字体的额外配置

上述配置完成之后执行 ./gradlew asciidoctor 已经可以生成 html5、pdf 了,不过打开 pdf 的话会发现中文乱码,中文都变成了¬ ,此问题可参见官方说明 Built-In (AFM) Fonts

提示如下:

The following text could not be fully converted to the Windows-1252 character set:
| <string with unknown glyph>

PDF 乱码示例:

pdf 乱码示例

之所以乱码主要是 asciidoctor-pdf 默认使用的 default-theme.yml 中配置的字体文件不支持中文,点开看看这个文件就知道怎么回事了。

可以去 asciidoctor-pdf-cjk-kai_gen_gothic 下载「怀源黑体」(思源黑体的 ttf 版)和「Roboto Mono」等宽字体,放置到 data/fonts 下面。

之后编写 data/themes/basic-theme.yml

#
# 重载 https://github.com/asciidoctor/asciidoctor-pdf/blob/master/data/themes/default-theme.yml
# 使用中文字体解决 pdf 乱码问题
#

extends: default

# 重载字体定义
font:
    catalog:
        KaiGen Gothic CN:
            normal: KaiGenGothicCN-Regular.ttf
            bold: KaiGenGothicCN-Bold.ttf
            italic: KaiGenGothicCN-Regular-Italic.ttf
            bold_italic: KaiGenGothicCN-Bold-Italic.ttf
        Roboto Mono:
            normal: RobotoMono-Regular.ttf
            bold: RobotoMono-Bold.ttf
            italic: RobotoMono-Italic.ttf
            bold_italic: RobotoMono-BoldItalic.ttf
    fallbacks:
        - KaiGen Gothic CN

# 覆盖基础字体
base:
    font_family: KaiGen Gothic CN

# 覆盖等宽字体
literal:
    font_family: Roboto Mono

最后在 build.gradle 中配置:

    attributes 'pdf-fontsdir': file('data/fonts')
    attributes 'pdf-stylesdir': file('data/themes')
    attributes 'pdf-style': 'basic'

update: 测试发现单纯使用上面配置并不能解决 code 中的中文乱码, extends 属性貌似没起作用,去开发者 GitHub 上发了个 issue,尚无回复,目前的解决办法是直接拷贝 default-theme.yml ,然后增加覆盖掉相应字体配置即可。具体示例参见: KaiGenGothicCN-theme.yml

Spring REST Docs 版本要求

asciidoc 的另一个使用场景是配合 Spring REST Docs 生成 api 文档,不过需要注意的是这时候只能使用 1.5.x 版本的 org.asciidoctor.convert ,因为 Spring REST Docs 暂时还不支持新版 asciidoctor

这时候需要注意 build.gradle 中一些配置需要调整,例如:

    outputOptions {
        backends = ['html5', 'pdf']
    }

需要调整为:

backends 'html5', 'pdf'

参考

© 著作权归作者所有

郁也风
粉丝 16
博文 31
码字总数 17009
作品 0
长宁
项目经理
私信 提问
swagger-ui + swagger2markup-cli + asciidoctor 生成api文档

参考:https://segmentfault.com/a/1190000017873594?utmsource=tag-newest swagger-ui地址为:http://sample.com:8888/zk/swagger-ui.html 通过https://github.com/Swagger2Markup/swagger......

莫在全
05/20
79
0
Asciidoctor Maven 插件

参考资料 1,使用Swagger2Markup、asciidoctor-maven-plugin和asciidoctorj-pdf插件生成PDF格式的API文档中文问题解决 2、asciidoc最佳实践-maven插件 3、Asciidoctor Maven插件使用 4、Asc...

近在咫尺远在天涯
05/07
80
0
gradle spring一直报错

使用spring3.2 gradle1.6 * What went wrong: A problem occurred configuring root project 'spring'. > Could not resolve all dependencies for configuration ':classpath'. > Could not......

kurumi
2016/05/30
5.7K
1
RESTful API 文档生成工具--API-doc

RESTful API 标准文档生成工具,可生成直观的HTML形式、PDF格式的文档,方便API开发者查阅。 1. 遵循OpenAPI规范编写RESTful API的接口定义 2. 生成直观的HTML和PDF格式的文档 3. 对中文的完...

一刀
2017/06/25
3.8K
1
Build RESTful APIs with Spring MVC: Swagger

Visualizes REST APIs with Swagger Swagger is widely used for visualizing APIs, and with Swagger UI it provides online sandbox for frontend developers. Visualizes REST APIs Sprin......

hantsy
2016/07/25
154
0

没有更多内容

加载失败,请刷新页面

加载更多

nginx学习笔记

中间件位于客户机/ 服务器的操作系统之上,管理计算机资源和网络通讯。 是连接两个独立应用程序或独立系统的软件。 web请求通过中间件可以直接调用操作系统,也可以经过中间件把请求分发到多...

码农实战
今天
5
0
Spring Security 实战干货:玩转自定义登录

1. 前言 前面的关于 Spring Security 相关的文章只是一个预热。为了接下来更好的实战,如果你错过了请从 Spring Security 实战系列 开始。安全访问的第一步就是认证(Authentication),认证...

码农小胖哥
今天
12
0
JAVA 实现雪花算法生成唯一订单号工具类

import lombok.SneakyThrows;import lombok.extern.slf4j.Slf4j;import java.util.Calendar;/** * Default distributed primary key generator. * * <p> * Use snowflake......

huangkejie
昨天
12
0
PhotoShop 色调:RGB/CMYK 颜色模式

一·、 RGB : 三原色:红绿蓝 1.通道:通道中的红绿蓝通道分别对应的是红绿蓝三种原色(RGB)的显示范围 1.差值模式能模拟三种原色叠加之后的效果 2.添加-颜色曲线:调整图像RGB颜色----R色增强...

东方墨天
昨天
11
1
将博客搬至CSDN

将博客搬至CSDN

算法与编程之美
昨天
13
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部