path: root/documentation/content/en/books/fdp-primer/doc-build/_index.adoc

---
title: Chapter 5. The FreeBSD Documentation Build Process
prev: books/fdp-primer/structure
next: books/fdp-primer/asciidoctor-primer
description: Describes the FreeBSD Documentation Build Process
tags: ["build", "process", "make"]
showBookMenu: true
weight: 6
path: "/books/fdp-primer/"
---

[[doc-build]]
= The FreeBSD Documentation Build Process
: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::[]

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

Advanced build examples are given below:

[[documentation-build-example-verbose]]
.Build the documentation with verbose and debug messages
[example]
====
[source,shell]
....
% cd ~/doc/documentation
% make HUGO_ARGS="--verbose --debug --path-warnings"
....
====

[[documentation-build-example-server]]
.Build and serve the content with Hugo’s internal webserver
[example]
====
[source,shell]
....
% 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:

[source,shell]
....
% make run BIND=192.168.15.10
....

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

[source,shell]
....
% make run BIND=192.168.15.10 HOSTNAME=example.com
....
====

[[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 using the `-r` argument.

[[document-pdf-example]]
.Build a document in pdf
[example]
====
[source,shell]
....
% 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
....
====

[[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 <.>
RUBYLIB =	../shared/lib
.export	RUBYLIB

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

.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 --baseURL="http://$(.HOST):1313"

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 <.>
RUBYLIB =	../shared/lib
.export	RUBYLIB

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

.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 --baseURL="http://$(.HOST):1313"

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