Capítulo 5. Processo de Compilação da Documentação do FreeBSD

Esta tradução pode estar desatualizada. Para ajudar com as traduções, acesse a ferramenta de traduções do FreeBSD.

Índice

Este capítulo cobre a organização do processo de compilação da documentação e como o make(1) é usado para controlá-lo.

5.1. Renderizando AsciiDoc

Diferentes tipos de formato podem ser gerados a partir de um único arquivo AsciiDoc.

Formatos Tipo de Arquivo Descrição

Formatos	Tipo de Arquivo	Descrição
`html`	HTML	Um capítulo de `artigo` ou `livro`.
`pdf`	PDF	Portable Document Format.
`epub`	EPUB	Electronic Publication. ePub file format.

html

HTML

Um capítulo de artigo ou livro.

pdf

PDF

Portable Document Format.

epub

EPUB

Electronic Publication. ePub file format.

5.1.1. Renderizando em html

Para renderizar a documentação e o site em html, use um dos seguintes exemplos.

Exemplo 1. Compile a documentação

% cd ~/doc/documentation
% make

Exemplo 2. Compile o website

% cd ~/doc/website
% make

Exemplo 3. Compile todo o projeto de documentação

% cd ~/doc
% make -j2

Exemplos avançados de compilação são apresentados abaixo:

Exemplo 4. Compile a documentação em Inglês e Espanhol com mensagens de debug e no modo verboso

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

Exemplo 5. Compile e sirva o conteúdo com o servidor web interno do Hugo

% cd ~/doc/documentation
% make run

Este servidor web roda em localhost, porta`1313` por padrão.

Para servir o conteúdo com o servidor web interno do Hugo em um endereço IP e porta específicos:

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

Um hostname também pode ser definido como url base para o servidor web interno do Hugo:

% make run BIND=192.168.15.10 HOSTNAME=example.com

Exemplo 6. Compile a documentação em html para uso offline

% cd ~/doc/documentation
% make html

Para compactar a saída em html, adicione DOC_HTML_ARCHIVE=1:

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

5.1.2. Renderizando em pdf

Para gerar a documentação em pdf, use um dos seguintes exemplos.

Exemplo 7. Compilar todos os documentos em pdf

% cd ~/doc/documentation
% make pdf

Exemplo 8. Compilar todos os artigos em pdf

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

Exemplo 9. Compilar todos os livros em pdf

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

Exemplo 10. Compilar todos os documentos em pdf de um idioma em específico

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

Este comando irá compilar todos os documentos em pdf do idioma Inglês.

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

Este comando irá compilar todos os livros em pdf dos idiomas Inglês e Francês.

5.2. O Conjunto de Ferramentas de Compilação da Documentação do FreeBSD

Essas são as ferramentas usadas para compilar e instalar a documentação FDP.

A principal ferramenta de compilação é o make(1), especificamente o Berkeley Make.
Hugo
AsciiDoctor
Git

5.3. Compreendendo o Makefile na Árvore de Documentação

Existem três arquivos Makefile para compilar em parte ou todo o projeto de documentação.

O Makefile no diretório documentation irá compilar apenas a documentação.
O Makefile no diretório website irá compilar apenas a website.
O Makefile na raíz irá compilar a documentação e o site.

O Makefile dos subdiretórios também suportam make run para servir o conteúdo compilado com o servidor web interno do Hugo. Este servidor web roda na porta 1313 por padrão.

5.3.1. Makefile da Documentação

Este Makefile suporta o seguinte:

# Generate the FreeBSD documentation
#
# Copyright (c) 2020-2021, The FreeBSD Documentation Project
# Copyright (c) 2020-2021, Sergio Carlavilla <carlavilla@FreeBSD.org>
#
# 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=carlavilla@FreeBSD.org (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	A flag `MAINTAINER` especifica quem é o mantenedor deste Makefile.
2	A flag `ALL_LANGUAGES` especifica em quais idiomas o índice deve ser gerado.
3	A flag `RUBY_CMD` especifica a localização do binário Ruby.
4	A flag `HUGO_CMD` especifica a localização do binário Hugo.
5	As diretivas `.ORDER` são usadas para garantir que vários makes possam ser executados sem problemas.
6	O target `all` gera os índices dos livros ("TOCs"), compila a documentação e coloca o resultado em ~/doc/documentation/public.
7	`starting-message` mostra uma mensagem no console para mostrar ao usuário que o processo está em execução.
8	`run-local` executa o servidor web hugo na porta 1313, ou uma porta livre aleatória se esta já estiver em uso.
9	`build` compila a documentação e coloca o resultado em ~/doc/documentation/public.

5.3.2. Makefile do Website

Este é o Makefile:

# Generate the FreeBSD website
#
# Copyright (c) 2020-2021, The FreeBSD Documentation Project
# Copyright (c) 2020-2021, Sergio Carlavilla <carlavilla@FreeBSD.org>
#
# 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=carlavilla@FreeBSD.org (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 "---------------------------------------------------------------"

starting-message: .PHONY (7)
	@echo ---------------------------------------------------------------
	@echo                   Building the website
	@echo ---------------------------------------------------------------

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

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

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

build: .PHONY (10)
	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	A flag `MAINTAINER` especifica quem é o mantenedor deste Makefile.
2	A flag `RUBY_CMD` especifica a localização do binário Ruby.
3	A flag `HUGO_CMD` especifica a localização do binário Hugo.
4	As diretivas `.ORDER` são usadas para garantir que vários makes possam ser executados sem problemas.
5	O target `all` compila o website e coloca o resultado em ~/doc/website/public.
6	`starting-message` mostra uma mensagem no console para mostrar ao usuário que o processo está em execução.
7	`generate-releases` chama o script usado para converter as variáveis AsciiDoc em variáveis TOML. Com esta conversão, as variáveis de releases podem ser utilizadas no AsciiDoc e nos templates personalizados do Hugo.
8	`run-local` executa o servidor web hugo na porta 1313, ou uma porta livre aleatória se esta já estiver em uso.
9	`build` compila o website e coloca o resultado em ~/doc/website/public.

Última alteração em: 9 de março de 2024 por Danilo G. Baio

Início