Chapter 5. The FreeBSD Documentation Build Process

This chapter covers organization of the documentation build process and how make(1) is used to control it.

5.1. Rendering AsciiDoc into Output

Different types of output can be produced from a single AsciiDoc source file.

FormatsFile TypeDescription

html

HTML

An article or book chapter.

pdf

PDF

Portable Document Format.

epub

EPUB

Electronic Publication. ePub file format.

5.1.1. Rendering to html

To render the documentation and the website to html use one of the following examples.

Example 1. Build the documentation
% cd ~/doc/documentation
% make
Example 2. Build the website
% cd ~/doc/website
% make
Example 3. Build the entire documentation project
% cd ~/doc
% make -j2

Advanced build examples are given below:

Example 4. Build the documentation with verbose and debug messages
% cd ~/doc/documentation
% make HUGO_ARGS="--verbose --debug --path-warnings"
Example 5. Build and serve the content with Hugo’s internal webserver
% cd ~/doc/documentation
% make run

This webserver runs on localhost, port 1313 by default.

To serve the content with Hugo’s internal webserver binding a specific IP address:

% make run BIND=192.168.15.10

A hostname can also be set as base url to Hugo’s internal webserver:

% make run BIND=192.168.15.10 HOSTNAME=example.com

5.1.2. Rendering to pdf

To generate a document in pdf format use this command. In this example the English Handbook will be used. In order to export the document correctly all the extensions should be passed using the -r argument.

Example 6. Build a document in pdf
% cd ~/doc/documentation
% asciidoctor-pdf \
  -r ./shared/lib/man-macro.rb \
  -r ./shared/lib/git-macro.rb \
  -r ./shared/lib/packages-macro.rb \
  -r ./shared/lib/inter-document-references-macro.rb \
  -r ./shared/lib/sectnumoffset-treeprocessor.rb \
  --doctype=book \
  -a skip-front-matter \
  -a pdf-theme=./themes/default-pdf-theme.yml \
  -o /tmp/handbook.pdf \
  content/en/books/handbook/book.adoc

5.2. The FreeBSD Documentation Build Toolset

These are the tools used to build and install the FDP documentation.

  • The primary build tool is make(1), specifically Berkeley Make.

  • Python is used to generate the Table of Contents and other related Tables.

  • Hugo

  • AsciiDoctor

  • Git

5.3. Understanding the Makefile in the Documentation Tree

There are three Makefile files for building some or all of the documentation project.

  • The Makefile in the documentation directory will build only the documentation.

  • The Makefile in the website directory will build only the website.

  • The Makefile at the top of the tree will build both the documentation and the website.

The Makefile appearing in subdirectories also support make run to serve built content with Hugo’s internal webserver. This webserver runs on port 1313 by default.

5.3.1. Documentation Makefile

This Makefile takes the following form:

# 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
# run	-			serves the built documentation site for local browsing
#
# 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)

PYTHON_CMD =	/usr/local/bin/python3 (2)
HUGO_CMD =	/usr/local/bin/hugo (3)
LANGUAGES =	en,es,pt_BR,de,ja,zh_CN,zh_TW,ru,el,hu,it,mn,nl,pl,fr (4)
RUBYLIB =	../shared/lib
.export	RUBYLIB

.ifndef HOSTNAME
.HOST+=localhost
.else
.HOST+=$(HOSTNAME)
.endif

.ORDER: all run(5)

.ORDER: starting-message generate-books-toc
.ORDER: starting-message build
.ORDER: generate-books-toc build

all: starting-message generate-books-toc build (6)

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

generate-books-toc: .PHONY (8)
	${PYTHON_CMD} ./tools/books-toc-parts-creator.py -l ${LANGUAGES}
	${PYTHON_CMD} ./tools/books-toc-creator.py -l ${LANGUAGES}
	${PYTHON_CMD} ./tools/books-toc-figures-creator.py -l ${LANGUAGES}
	${PYTHON_CMD} ./tools/books-toc-tables-creator.py -l ${LANGUAGES}
	${PYTHON_CMD} ./tools/books-toc-examples-creator.py -l ${LANGUAGES}

run: .PHONY (9)
	${HUGO_CMD} server -D --baseURL="http://$(.HOST):1313"

build: .PHONY (10)
	${HUGO_CMD} --minify
1The MAINTAINER flag specifies who is the maintainer of this Makefile.
2PYTHON_CMD flag specifies the location of the Python binary.
3HUGO_CMD flag specifies the location of the Hugo binary.
4LANGUAGES flag specifies in which languages the table of contents has to be generated.
5.ORDER directives are used to ensure multiple make jobs may run without problem.
6all target generates the books' tables of contents ("TOCs"), builds the documentation and puts the result in ~/doc/documentation/public.
7starting-message shows a message in the CLI to show the user that the process is running.
8generate-books-toc calls the scripts to generate the books TOCs.
9run runs hugo webserver on port 1313, or a random free port if that is already in use.
10build builds the documentation and puts the result in the ~/doc/documentation/public.

5.3.2. Website Makefile

This Makefile takes the form of:

# 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 documentation site for local browsing
#
# 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)

PYTHON_CMD =	/usr/local/bin/python3 (2)
HUGO_CMD =	/usr/local/bin/hugo (3)
RUBYLIB =	../shared/lib
.export	RUBYLIB

.ifndef HOSTNAME
.HOST+=localhost
.else
.HOST+=$(HOSTNAME)
.endif

.ORDER: all run(4)

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

all: starting-message generate-releases run (5)

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

generate-releases: .PHONY (7)
	${PYTHON_CMD} ./tools/releases-toml.py -p ./shared/releases.adoc

run: .PHONY (8)
	${HUGO_CMD} server -D --baseURL="http://$(.HOST):1313"

build: .PHONY (9)
	${HUGO_CMD}
1The MAINTAINER flag specifies who is the maintainer of this Makefile.
2PYTHON_CMD flag specifies the location of the Python binary.
3HUGO_CMD flag specifies the location of the Hugo binary.
4.ORDER directives are used to ensure multiple make jobs may run without problem.
5all target builds the website and puts the result in ~/doc/website/public.
6starting-message shows a message in the CLI to show the user that the process is running.
7generate-releases calls the script used to convert from AsciiDoc variables to TOML variables. With this conversion, the releases variables can be used in AsciiDoc and in the Hugo custom templates.
8run runs hugo webserver on port 1313, or a random free port if that is already in use.
9build builds the website and puts the result in the ~/doc/website/public.

All FreeBSD documents are available for download at https://download.freebsd.org/ftp/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.