---
title: Chapter 5. The FreeBSD Documentation Build Process
prev: books/fdp-primer/structure
next: books/fdp-primer/asciidoctor-primer
---

[[doc-build]]
= The FreeBSD Documentation Build Process
:doctype: book
:toc: macro
:toclevels: 1
:icons: font
:sectnums:
:sectnumlevels: 6
:source-highlighter: rouge
:experimental:
:skip-front-matter:
:xrefstyle: basic
:relfileprefix: ../
:outfilesuffix:
:sectnumoffset: 5

toc::[] 

This chapter covers organization of the documentation build process and how man:make[1] is used to control it.

[[doc-build-rendering]]
== Rendering AsciiDoc into Output

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

[cols="20%,20%,60%", frame="none", options="header"]
|===
| Formats
| File Type
| Description

|`html`
|HTML
|An `article` or `book` chapter.

|`pdf`
|PDF
|Portable Document Format.

|`epub`
|EPUB
|Electronic Publication. ePub file format.
|===

[[doc-build-rendering-html]]
=== Rendering to html

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

[[documentation-build-example]]
.Build the documentation
[example]
====
[source,shell]
....
% cd ~/doc/documentation
% make
....
====

[[website-build-example]]
.Build the website
[example]
====
[source,shell]
....
% cd ~/doc/website
% make
....
====

[[project-build-example]]
.Build the entire documentation project
[example]
====
[source,shell]
....
% cd ~/doc
% make -j2
....
====

[[doc-build-rendering-pdf]]
=== 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 used the `-r` argument.

[[document-pdf-example]]
.Build the entire documentation project
[example]
====
[source,shell]
....
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 content/en/books/handbook/book.adoc
....
====

[[doc-build-toolset]]
== The FreeBSD Documentation Build Toolset

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

* The primary build tool is man:make[1], specifically Berkeley Make.
* Python is used to generate the Table of Contents and other related Tables.
* Hugo
* AsciiDoctor
* Git

[[doc-build-makefile]]
== Understanding the Makefile in the Documentation Tree

There are three [.filename]#Makefile# files for building some or all of the documentation project.

* The [.filename]#Makefile# in the [.filename]#documentation# directory will build only the documentation.
* The [.filename]#Makefile# in the [.filename]#website# directory will build only the website.
* The [.filename]#Makefile# at the top of the tree will build both the documentation and the website.

The [.filename]#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.

[[documentation-makefile]]
=== Documentation Makefile

This [.filename]#Makefile# takes the following form:

[source,shell]
....
# 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 <.>

PYTHON_CMD =	/usr/local/bin/python3 <.>
HUGO_CMD =	/usr/local/bin/hugo <.>
LANGUAGES =	en,es,pt_BR,de,ja,zh_CN,zh_TW,ru,el,hu,it,mn,nl,pl,fr <.>

.ORDER: all run<.>

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

all: starting-message generate-books-toc build <.>

starting-message: .PHONY <.>
	@echo ---------------------------------------------------------------
	@echo                   Building the documentation
	@echo ---------------------------------------------------------------

generate-books-toc: .PHONY <.>
	${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 <.>
	${HUGO_CMD} server -D

build: .PHONY <.>
	${HUGO_CMD} --minify
....

<.> The `MAINTAINER` flag specifies who is the maintainer of this Makefile.
<.> `PYTHON_CMD` flag specifies the location of the Python binary.
<.> `HUGO_CMD` flag specifies the location of the Hugo binary.
<.> `LANGUAGES` flag specifies in which languages the table of contents has to be generated.
<.> `.ORDER` directives are used to ensure multiple make jobs may run without problem.
<.> `all` target generates the books' tables of contents ("TOCs"), builds the documentation and puts the result in [.filename]#~/doc/documentation/public#.
<.> `starting-message` shows a message in the CLI to show the user that the process is running.
<.> `generate-books-toc` calls the scripts to generate the books TOCs.
<.> `run` runs hugo webserver on port 1313, or a random free port if that is already in use.
<.> `build` builds the documentation and puts the result in the [.filename]#~/doc/documentation/public#.

[[website-makefile]]
=== Website Makefile

This [.filename]#Makefile# takes the form of:

[source,shell]
....
# 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 <.>

PYTHON_CMD =	/usr/local/bin/python3 <.>
HUGO_CMD =	/usr/local/bin/hugo <.>

.ORDER: all run<.>

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

all: starting-message generate-releases run <.>

starting-message: .PHONY <.>
	@echo ---------------------------------------------------------------
	@echo                   Building the website
	@echo ---------------------------------------------------------------

generate-releases: .PHONY <.>
	${PYTHON_CMD} ./tools/releases-toml.py -p ./shared/releases.adoc

run: .PHONY <.>
	${HUGO_CMD} server -D

build: .PHONY <.>
	${HUGO_CMD}
....

<.> The `MAINTAINER` flag specifies who is the maintainer of this Makefile.
<.> `PYTHON_CMD` flag specifies the location of the Python binary.
<.> `HUGO_CMD` flag specifies the location of the Hugo binary.
<.> `.ORDER` directives are used to ensure multiple make jobs may run without problem.
<.> `all` target builds the website and puts the result in [.filename]#~/doc/website/public#.
<.> `starting-message` shows a message in the CLI to show the user that the process is running.
<.> `generate-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.
<.> `run` runs hugo webserver on port 1313, or a random free port if that is already in use.
<.> `build` builds the website and puts the result in the [.filename]#~/doc/website/public#.
