Path: blob/main/documentation/content/pt-br/books/fdp-primer/doc-build/_index.adoc
18099 views
---
description: 'Descreve o Processo de Compilação da Documentação do FreeBSD'
next: books/fdp-primer/asciidoctor-primer
params:
path: /books/fdp-primer/doc-build/
prev: books/fdp-primer/structure
showBookMenu: 'true'
tags: ["build", "process", "make"]
title: 'Capítulo 5. Processo de Compilação da Documentação do FreeBSD'
weight: 6
---
[[doc-build]]
= Processo de Compilação da Documentação do FreeBSD
:doctype: book
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:sectnumlevels: 6
:sectnumoffset: 5
:partnums:
:source-highlighter: rouge
:experimental:
:images-path: books/fdp-primer/
ifdef::env-beastie[]
ifdef::backend-html5[]
:imagesdir: ../../../../images/{images-path}
endif::[]
ifndef::book[]
include::shared/authors.adoc[]
include::shared/mirrors.adoc[]
include::shared/releases.adoc[]
include::shared/attributes/attributes-{{% lang %}}.adoc[]
include::shared/{{% lang %}}/teams.adoc[]
include::shared/{{% lang %}}/mailing-lists.adoc[]
include::shared/{{% lang %}}/urls.adoc[]
toc::[]
endif::[]
ifdef::backend-pdf,backend-epub3[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]
endif::[]
ifndef::env-beastie[]
toc::[]
include::../../../../../shared/asciidoctor.adoc[]
endif::[]
Este capítulo cobre a organização do processo de compilação da documentação e como o man:make[1] é usado para controlá-lo.
[[doc-build-rendering]]
== Renderizando AsciiDoc
Diferentes tipos de formato podem ser gerados a partir de um único arquivo AsciiDoc.
[cols="20%,20%,60%", frame="none", options="header"]
|===
| 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.
|===
[[doc-build-rendering-html]]
=== Renderizando em html
Para renderizar a documentação e o site em `html`, use um dos seguintes exemplos.
[[documentation-build-example]]
.Compile a documentação
[example]
====
[source, shell]
....
% cd ~/doc/documentation
% make
....
====
[[website-build-example]]
.Compile o website
[example]
====
[source, shell]
....
% cd ~/doc/website
% make
....
====
[[project-build-example]]
.Compile todo o projeto de documentação
[example]
====
[source, shell]
....
% cd ~/doc
% make -j2
....
====
Exemplos avançados de compilação são apresentados abaixo:
[[documentation-build-example-verbose]]
.Compile a documentação em Inglês e Espanhol com mensagens de debug e no modo verboso
[example]
====
[source, shell]
....
% cd ~/doc/documentation
% make DOC_LANG="en es" HUGO_ARGS="--verbose --debug"
....
====
[[documentation-build-example-server]]
.Compile e sirva o conteúdo com o servidor web interno do Hugo
[example]
====
[source, shell]
....
% 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:
[source, shell]
....
% 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:
[source, shell]
....
% make run BIND=192.168.15.10 HOSTNAME=example.com
....
====
[[documentation-build-example-offline]]
.Compile a documentação em html para uso offline
[example]
====
[source, shell]
....
% cd ~/doc/documentation
% make html
....
Para compactar a saída em html, adicione `DOC_HTML_ARCHIVE=1`:
[source, shell]
....
% cd ~/doc/documentation
% DOC_HTML_ARCHIVE=1 make html
....
====
[[doc-build-rendering-pdf]]
=== Renderizando em pdf
Para gerar a documentação em `pdf`, use um dos seguintes exemplos.
[[document-pdf-example]]
.Compilar todos os documentos em pdf
[example]
====
[source, shell]
....
% cd ~/doc/documentation
% make pdf
....
====
[[document-pdf-articles-example]]
.Compilar todos os artigos em pdf
[example]
====
[source, shell]
....
% cd ~/doc/documentation
% make pdf-articles
....
====
[[document-pdf-books-example]]
.Compilar todos os livros em pdf
[example]
====
[source, shell]
....
% cd ~/doc/documentation
% make pdf-books
....
====
[[document-pdf-language-example]]
.Compilar todos os documentos em pdf de um idioma em específico
[example]
====
[source, shell]
....
% cd ~/doc/documentation
% make DOC_LANG="en" pdf
....
Este comando irá compilar todos os documentos em pdf do idioma Inglês.
[source, shell]
....
% 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.
====
[[doc-build-toolset]]
== 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 man:make[1], especificamente o Berkeley Make.
* Hugo
* AsciiDoctor
* Git
[[doc-build-makefile]]
== Compreendendo o Makefile na Árvore de Documentação
Existem três arquivos [.filename]#Makefile# para compilar em parte ou todo o projeto de documentação.
* O [.filename]#Makefile# no diretório [.filename]#documentation# irá compilar apenas a documentação.
* O [.filename]#Makefile# no diretório [.filename]#website# irá compilar apenas a website.
* O [.filename]#Makefile# na raíz irá compilar a documentação e o site.
O [.filename]#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.
[[documentation-makefile]]
=== Makefile da Documentação
Este [.filename]#Makefile# suporta o seguinte:
[source, shell]
....
# Generate the FreeBSD documentation
#
# Copyright (c) 2020-2025, The FreeBSD Documentation Project
# Copyright (c) 2020-2025, 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.
[email protected] <.>
# 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 <.>
LOCALBASE?= /usr/local
RUBY_CMD = ${LOCALBASE}/bin/ruby <.>
HUGO_CMD = ${LOCALBASE}/bin/hugo <.>
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 <.>
.ORDER: requirements <.>
.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 <.>
@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 <.>
HUGO_DISABLELANGUAGES="${SKIP_LANGS}" ${HUGO_CMD} server \
${HUGO_ARGS} -D $(BIND:D--bind=$(BIND)) --baseURL="http://$(.HOST):1313"
build: .PHONY <.>
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
....
<.> A flag `MAINTAINER` especifica quem é o mantenedor deste Makefile.
<.> A flag `ALL_LANGUAGES` especifica em quais idiomas o índice deve ser gerado.
<.> A flag `RUBY_CMD` especifica a localização do binário Ruby.
<.> A flag `HUGO_CMD` especifica a localização do binário Hugo.
<.> As diretivas `.ORDER` são usadas para garantir que vários makes possam ser executados sem problemas.
<.> O target `all` gera os índices dos livros ("TOCs"), compila a documentação e coloca o resultado em *~/doc/documentation/public*.
<.> `starting-message` mostra uma mensagem no console para mostrar ao usuário que o processo está em execução.
<.> `run-local` executa o servidor web hugo na porta 1313, ou uma porta livre aleatória se esta já estiver em uso.
<.> `build` compila a documentação e coloca o resultado em *~/doc/documentation/public*.
[[website-makefile]]
=== Makefile do Website
Este é o [.filename]#Makefile#:
[source, shell]
....
# Generate the FreeBSD website
#
# Copyright (c) 2020-2025, The FreeBSD Documentation Project
# Copyright (c) 2020-2025, 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.
[email protected] <.>
# 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 <.>
HUGO_CMD = ${LOCALBASE}/bin/hugo <.>
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 <.>
.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 <.>
run: starting-message generate-releases run-local
clean: hugo-clean releases-clean
starting-message: .PHONY <.>
@echo "---------------------------------------------------------------"
@echo "Building the website started on $$(date)"
@echo " included languages: ${LANGUAGES}"
@echo " excluded languages: ${SKIP_LANGS}"
@echo "---------------------------------------------------------------"
starting-message: .PHONY <.>
@echo ---------------------------------------------------------------
@echo Building the website
@echo ---------------------------------------------------------------
generate-releases: data/releases.toml <.>
data/releases.toml:
${RUBY_CMD} ./tools/releases-toml.rb
run-local: .PHONY <.>
HUGO_DISABLELANGUAGES="${SKIP_LANGS}" ${HUGO_CMD} server \
${HUGO_ARGS} -D $(BIND:D--bind=$(BIND)) --baseURL="http://$(.HOST):1313"
build: .PHONY <.>
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
....
<.> A flag `MAINTAINER` especifica quem é o mantenedor deste Makefile.
<.> A flag `RUBY_CMD` especifica a localização do binário Ruby.
<.> A flag `HUGO_CMD` especifica a localização do binário Hugo.
<.> As diretivas `.ORDER` são usadas para garantir que vários makes possam ser executados sem problemas.
<.> O target `all` compila o website e coloca o resultado em *~/doc/website/public*.
<.> `starting-message` mostra uma mensagem no console para mostrar ao usuário que o processo está em execução.
<.> `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.
<.> `run-local` executa o servidor web hugo na porta 1313, ou uma porta livre aleatória se esta já estiver em uso.
<.> `build` compila o website e coloca o resultado em *~/doc/website/public*.