第 5 章. FreeBSD 文档构建流程

5.1. 将 AsciiDoc 渲染成输出

可以从单个 AsciiDoc 源文件生成不同类型的输出。

格式文件类型描述

格式	文件类型	描述
`html`	HTML	一个 `article` 或 `book` 章节。
`pdf`	PDF	便携式文档格式。
`epub`	EPUB	电子出版物。ePub 文件格式。

html

HTML

一个 article 或 book 章节。

pdf

PDF

便携式文档格式。

epub

EPUB

电子出版物。ePub 文件格式。

5.1.1. 渲染到 html

要将文档和网站渲染到 html，请使用以下示例之一。

示例 1. 构建文档

% cd ~/doc/documentation
% make

示例 2. 构建网站

% cd ~/doc/website
% make

示例 3. 构建整个文档项目

% cd ~/doc
% make -j2

下面给出高级构建示例

示例 4. 使用详细和调试消息构建英语和西班牙语文档

% cd ~/doc/documentation
% make DOC_LANG="en es" HUGO_ARGS="--verbose --debug"

示例 5. 使用 Hugo 的内部 Web 服务器构建和提供内容

% cd ~/doc/documentation
% make run

此 Web 服务器默认在 localhost 的 1313 端口上运行。

要使用 Hugo 的内部 Web 服务器提供内容并绑定特定的 IP 地址和端口

% make run BIND=192.168.15.10 HUGO_ARGS="-p 8080"

还可以将 主机名 设置为 Hugo 内部 Web 服务器的基本 URL

% make run BIND=192.168.15.10 HOSTNAME=example.com

示例 6. 构建用于离线使用的 html 文档

% cd ~/doc/documentation
% make html

要压缩 html 输出，请添加 DOC_HTML_ARCHIVE=1

% cd ~/doc/documentation
% DOC_HTML_ARCHIVE=1 make html

5.1.2. 渲染到 pdf

要将文档渲染到 pdf，请使用以下示例之一。

示例 7. 构建所有 pdf 文档

% cd ~/doc/documentation
% make pdf

示例 8. 构建所有 pdf 文章

% cd ~/doc/documentation
% make pdf-articles

示例 9. 构建所有 pdf 图书

% cd ~/doc/documentation
% make pdf-books

示例 10. 为特定语言构建 pdf 文档

% cd ~/doc/documentation
% make DOC_LANG="en" pdf

这将构建所有英语 pdf 文档。

% cd ~/doc/documentation
% make DOC_LANG="en fr" pdf-books

这将构建所有英语和法语 pdf 图书。

5.2. FreeBSD 文档构建工具集

这些是用于构建和安装 FDP 文档的工具。

主要构建工具是 make(1)，特别是 Berkeley Make。
Hugo
AsciiDoctor
Git

5.3. 了解文档树中的 Makefile

有三个 Makefile 文件用于构建部分或全部文档项目。

documentation 目录中的 Makefile 将只构建文档。
website 目录中的 Makefile 将只构建网站。
树顶部的 Makefile 将构建文档和网站。

出现在子目录中的 Makefile 也支持 make run 以使用 Hugo 的内部 Web 服务器提供构建的内容。此 Web 服务器默认在 1313 端口上运行。

5.3.1. 文档 Makefile

此 Makefile 采用以下形式

# Generate the FreeBSD documentation
#
# Copyright (c) 2020-2021, The FreeBSD Documentation Project
# Copyright (c) 2020-2021, Sergio Carlavilla <[email protected]>
#
# Targets intended for use on the command line
#
# all (default)	-	generate the books TOC and compile all the documentation
# clean		- 	removes generated files
# run		-	serves the built documentation site for local browsing
# pdf		-	build PDF versions of the articles and books.
# html		-	build HTML versions of the articles and books for
#			offline use.
#			If variable DOC_HTML_ARCHIVE is set, all documents will be
#			archived/compressed, and only these files will be kept in the public
#			directory.
# epub		-	build EPUB versions of the articles and books (Experimental).
#
# The run target uses hugo's built-in webserver to make the documentation site
# available for local browsing.  The documentation should have been built prior
# to attempting to use the `run` target.  By default, hugo will start its
# webserver on port 1313.

MAINTAINER=[email protected] (1)

# List of languages without book translations
ARTICLEONLY_LANGS=	bn-bd da ko tr
# List of languages without article translations
BOOKONLY_LANGS=		mn

# List of all languages we have content for
ALL_LANGUAGES=	bn-bd da de el en es fr hu it ja ko mn nl pl pt-br ru tr zh-cn zh-tw (2)

LOCALBASE?=	/usr/local

RUBY_CMD =	${LOCALBASE}/bin/ruby (3)
HUGO_CMD =	${LOCALBASE}/bin/hugo (4)
HUGO_ARGS?=	--verbose --minify
HUGO_OFFLINE_ARGS?= 	--environment offline --verbose --minify
ASCIIDOCTOR_CMD=	${LOCALBASE}/bin/asciidoctor
ASCIIDOCTORPDF_CMD=	${LOCALBASE}/bin/asciidoctor-pdf

.if defined(DOC_LANG) && !empty(DOC_LANG)
LANGUAGES=	${DOC_LANG:S/,/ /g}
.if  ${LANGUAGES:Men} == "" && ${.TARGETS:Mpdf*} == "" && ${.TARGETS:Mhtml*} == ""
.warning "Warning: cannot skip 'en'; adding it back"
LANGUAGES+=	en
.endif
.else
LANGUAGES=	${ALL_LANGUAGES}
.endif

RUBYLIB =	../shared/lib
.export	RUBYLIB

RUN_DEPENDS=	${HUGO_CMD} \
		${LOCALBASE}/bin/asciidoctor \
		${LOCALBASE}/bin/rougify

.ifndef HOSTNAME
.  ifdef BIND
.HOST=$(BIND)
.  else
.HOST=localhost
.  endif
.else
.HOST=$(HOSTNAME)
.endif

# Strip the languages with only articles from the list of languages we
#  will use to build books.
BOOK_LANGS= ${LANGUAGES}
.for a in ${ARTICLEONLY_LANGS}
BOOK_LANGS:=	${BOOK_LANGS:N${a}}
.endfor

# Strip the languages with only books from the list of languages we
#  will use to build articles.
ARTICLE_LANGS= ${LANGUAGES}
.for a in ${BOOKONLY_LANGS}
ARTICLE_LANGS:=	${ARTICLE_LANGS:N${a}}
.endfor

# Take the list of all languages, and take out the ones we have been
#   asked for.  We'll feed this to hugo.
SKIP_LANGS=
.for a in ${ALL_LANGUAGES}
.if  ${LANGUAGES:M${a}} == ""
SKIP_LANGS+=    ${a}
.endif
.endfor

.ORDER: all run (5)

.ORDER: requirements (6)
.ORDER: starting-message
.ORDER: starting-message build
.ORDER: build

all: requirements starting-message generate-pgpkeys-txt build
run: requirements starting-message generate-pgpkeys-txt run-local

# clean does not call pdf-clean as that is a subset of hugo-clean
clean: hugo-clean pgp-clean

requirements:
.for dep in ${RUN_DEPENDS}
.if !exists(${dep})
	@(echo ${dep} not found, please run 'pkg install docproj'; exit 1)
.endif
.endfor

requirements-pdf:
.if !exists(${LOCALBASE}/bin/asciidoctor-pdf)
	@(echo ${LOCALBASE}/bin/asciidoctor-pdf not found, please run 'pkg install rubygem-asciidoctor-pdf'; exit 1)
.endif

requirements-epub:
.if !exists(${LOCALBASE}/bin/asciidoctor-epub3)
	@(echo ${LOCALBASE}/bin/asciidoctor-epub3 not found, please run 'pkg install rubygem-asciidoctor-epub3'; exit 1)
.endif

starting-message: .PHONY (7)
	@echo ---------------------------------------------------------------
	@echo                   Building the documentation
	@echo  included languages: ${LANGUAGES}
	@echo  excluded languages: ${SKIP_LANGS}
	@echo ---------------------------------------------------------------

generate-pgpkeys-txt: static/pgpkeys/pgpkeys.txt

static/pgpkeys/pgpkeys.txt: static/pgpkeys/*key
	${RUBY_CMD} ./tools/global-pgpkeys-creator.rb

run-local: .PHONY (8)
	HUGO_DISABLELANGUAGES="${SKIP_LANGS}" ${HUGO_CMD} server \
		${HUGO_ARGS} -D $(BIND:D--bind=$(BIND)) --baseURL="http://$(.HOST):1313"

build: .PHONY (9)
	HUGO_DISABLELANGUAGES="${SKIP_LANGS}" ${HUGO_CMD} ${HUGO_ARGS}

build-offline: .PHONY
	HUGO_DISABLELANGUAGES="${SKIP_LANGS}" ${HUGO_CMD} ${HUGO_OFFLINE_ARGS}

pgp-clean: .PHONY
	rm -f static/pgpkeys/pgpkeys.txt

hugo-clean: .PHONY
	rm -rf resources public

#
# PDF targets
# Use DOC_LANG to choose the language, e.g., make DOC_LANG="en fr" pdf-books
#
pdf: pdf-articles pdf-books

pdf-books: requirements-pdf
.for _lang in ${BOOK_LANGS}
	./tools/asciidoctor.sh books ${_lang} pdf
.endfor

pdf-articles: requirements-pdf
.for _lang in ${ARTICLE_LANGS}
	./tools/asciidoctor.sh articles ${_lang} pdf
.endfor

pdf-clean: pdf-articles-clean pdf-books-clean

pdf-books-clean:
.for _lang in ${BOOK_LANGS}
	rm -fr ${.CURDIR}/public/${_lang}/books
	-rmdir ${.CURDIR}/public/${_lang}
.endfor
	-rmdir ${.CURDIR}/public/

pdf-articles-clean:
.for _lang in ${ARTICLE_LANGS}
	rm -fr ${.CURDIR}/public/${_lang}/articles
.if !exists(${.CURDIR}/public/${_lang}/books)
	rm -fr ${.CURDIR}/public/${_lang}
.endif
.endfor
	-rmdir ${.CURDIR}/public

#
# HTML targets
#
html: build-offline html-clean-global html-clean-articles html-clean-books html-archive html-archive-clean-files

html-clean: hugo-clean

html-clean-global:
	rm -fr ${.CURDIR}/public/index.html
	rm -rf pgpkeys js

html-clean-articles:
.for _lang in ${ARTICLE_LANGS}
	rm -fr ${.CURDIR}/public/${_lang}/index.html
	rm -fr ${.CURDIR}/public/${_lang}/articles/index.html
.endfor

html-clean-books:
.for _lang in ${BOOK_LANGS}
	rm -fr ${.CURDIR}/public/${_lang}/books/index.html
.endfor

html-archive:
.if defined(DOC_HTML_ARCHIVE)
.for _lang in ${ARTICLE_LANGS}
	./tools/asciidoctor.sh articles ${_lang} archive
.endfor
.for _lang in ${BOOK_LANGS}
	./tools/asciidoctor.sh books ${_lang} archive
.endfor
.endif

html-archive-clean-files:
.if defined(DOC_HTML_ARCHIVE)
	find ${.CURDIR}/public/ ! -name '*.pdf' ! -name '*.tar.gz' -type f -delete
	find ${.CURDIR}/public/ -type d -empty -delete
.endif

#
# EPUB targets
# Use DOC_LANG to choose the language, e.g., make DOC_LANG="en fr" epub-books
#
epub: epub-articles epub-books

epub-books: requirements-epub
	@echo ---------------------------------------------------------------
	@echo !!! EPUB output is experimental !!!
	@echo
	@echo Asciidoctor EPUB3 is currently alpha software. Use accordingly. Although the
	@echo bulk of AsciiDoc content is converted, there’s still work needed to fill in
	@echo gaps where conversion is incomplete or unstyled.
	@echo https://docs.asciidoctor.org/epub3-converter/latest/#project-status
	@echo ---------------------------------------------------------------
.for _lang in ${BOOK_LANGS}
	./tools/asciidoctor.sh books ${_lang} epub
.endfor

epub-articles: requirements-epub
	@echo ---------------------------------------------------------------
	@echo !!! EPUB output is experimental !!!
	@echo
	@echo Asciidoctor EPUB3 is currently alpha software. Use accordingly. Although the
	@echo bulk of AsciiDoc content is converted, there’s still work needed to fill in
	@echo gaps where conversion is incomplete or unstyled.
	@echo https://docs.asciidoctor.org/epub3-converter/latest/#project-status
	@echo ---------------------------------------------------------------
.for _lang in ${ARTICLE_LANGS}
	./tools/asciidoctor.sh articles ${_lang} epub
.endfor

epub-clean: epub-articles-clean epub-books-clean

epub-books-clean:
.for _lang in ${BOOK_LANGS}
	rm -fr ${.CURDIR}/public/${_lang}/books
	-rmdir ${.CURDIR}/public/${_lang}
.endfor
	-rmdir ${.CURDIR}/public/

epub-articles-clean:
.for _lang in ${ARTICLE_LANGS}
	rm -fr ${.CURDIR}/public/${_lang}/articles
.if !exists(${.CURDIR}/public/${_lang}/books)
	rm -fr ${.CURDIR}/public/${_lang}
.endif
.endfor
	-rmdir ${.CURDIR}/public

1	`MAINTAINER` 标志指定此 Makefile 的维护者。
2	`ALL_LANGUAGES` 标志指定必须生成目录的语言。
3	`RUBY_CMD` 标志指定 Ruby 二进制文件的路径。
4	`HUGO_CMD` 标志指定 Hugo 二进制文件的路径。
5	`.ORDER` 指令用于确保多个 make 作业可以无问题地运行。
6	`all` 目标构建文档并将结果放入 ~/doc/documentation/public 中。
7	`starting-message` 在 CLI 中显示一条消息，以向用户显示进程正在运行。
8	`run-local` 在 1313 端口上运行 hugo web 服务器，如果该端口已被使用，则运行随机的空闲端口。
9	`build` 构建文档并将结果放入 ~/doc/documentation/public 中。

5.3.2. 网站 Makefile

此 Makefile 采用以下形式

# Generate the FreeBSD website
#
# Copyright (c) 2020-2021, The FreeBSD Documentation Project
# Copyright (c) 2020-2021, Sergio Carlavilla <[email protected]>
#
# Targets intended for use on the command line
#
# all (default)	-	generate the releases.toml and compile all the website
# run	-			serves the built website for local browsing
#
# The run target uses hugo's built-in webserver to make the built website
# available for local browsing.  The website should have been built prior
# to attempting to use the `run` target.  By default, hugo will start its
# webserver on port 1313.

MAINTAINER=[email protected] (1)

# List of all languages we have content for
ALL_LANGUAGES=	de el en es fr hu it ja nl ru tr zh-cn zh-tw

LOCALBASE?=	/usr/local

RUBY_CMD =	${LOCALBASE}/bin/ruby (2)
HUGO_CMD =	${LOCALBASE}/bin/hugo (3)
HUGO_ARGS?=	--verbose
RUBYLIB =	../shared/lib
.export	RUBYLIB

.ifndef HOSTNAME
.  ifdef BIND
.HOST=$(BIND)
.  else
.HOST=localhost
.  endif
.else
.HOST=$(HOSTNAME)
.endif

.if defined(DOC_LANG) && !empty(DOC_LANG)
LANGUAGES=      ${DOC_LANG:S/,/ /g}
.if  ${LANGUAGES:Men} == ""
.warning "Warning: cannot skip 'en'; adding it back"
LANGUAGES+=	en
.endif
.else
LANGUAGES=	${ALL_LANGUAGES}
.endif

# Take the list of all languages, and take out the ones we have been
#   asked for via DOC_LANG.  We'll feed this to hugo.
SKIP_LANGS=
.for a in ${ALL_LANGUAGES}
.if ${LANGUAGES:M${a}} == ""
SKIP_LANGS+=	${a}
.endif
.endfor

.ORDER: all run (4)

.ORDER: starting-message generate-releases
.ORDER: starting-message build
.ORDER: generate-releases build
.ORDER: build post-build
.ORDER: post-build end-message

all: starting-message generate-releases build post-build end-message (5)
run: starting-message generate-releases run-local
clean: hugo-clean releases-clean

starting-message: .PHONY (6)
	@echo "---------------------------------------------------------------"
	@echo "Building the website started on $$(date)"
	@echo " included languages: ${LANGUAGES}"
	@echo " excluded languages: ${SKIP_LANGS}"
	@echo "---------------------------------------------------------------"

end-message: .PHONY
	@echo "---------------------------------------------------------------"
	@echo "Building the website completed on $$(date)"
	@echo "---------------------------------------------------------------"

generate-releases: data/releases.toml (7)

data/releases.toml:
	${RUBY_CMD} ./tools/releases-toml.rb

run-local: .PHONY (8)
	HUGO_DISABLELANGUAGES="${SKIP_LANGS}" ${HUGO_CMD} server \
	    ${HUGO_ARGS} -D $(BIND:D--bind=$(BIND)) --baseURL="http://$(.HOST):1313"

build: .PHONY (9)
	HUGO_DISABLELANGUAGES="${SKIP_LANGS}" ${HUGO_CMD} ${HUGO_ARGS}

post-build: cgi-permissions

cgi-permissions:
	@chmod 555 ./public/cgi/*.cgi

hugo-clean:
	rm -fr public resources

releases-clean:
	rm -f data/releases.toml

1	`MAINTAINER` 标志指定此 Makefile 的维护者。
2	`RUBY_CMD` 标志指定 Ruby 二进制文件的路径。
3	`HUGO_CMD` 标志指定 Hugo 二进制文件的路径。
4	`.ORDER` 指令用于确保多个 make 作业可以无问题地运行。
5	`all` 目标构建网站并将结果放入 ~/doc/website/public 中。
6	`starting-message` 在 CLI 中显示一条消息，以向用户显示进程正在运行。
7	`generate-releases` 调用用于将 AsciiDoc 变量转换为 TOML 变量的脚本。通过此转换，可以在 AsciiDoc 和 Hugo 自定义模板中使用 releases 变量。
8	`run-local` 在 1313 端口上运行 hugo web 服务器，如果该端口已被使用，则运行随机的空闲端口。
9	`build` 构建网站并将结果放入 ~/doc/website/public 中。

上次修改时间：2024 年 3 月 9 日，作者 Danilo G. Baio

首页