Capítulo 5. Processo de Compilação da Documentação do FreeBSD | FreeBSD Documentation Portal
Description: Descreve o Processo de Compilação da Documentação do FreeBSD
Keywords: build,process,make

# 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.

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
--- | --- | ---
`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-2025, The FreeBSD Documentation Project
    # Copyright (c) 2020-2025, 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-2025, The FreeBSD Documentation Project
    # Copyright (c) 2020-2025, 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: 18 de junho de 2026 por Alexander Ziaee

Anterior
Início
Próximo