Update build chapter in FDP

Update the build chapter in the FDP to reflect the new
build system.

Patch by:               kevans@
Differential Revision:  https://reviews.freebsd.org/D28409

1 files changed, 61 insertions, 24 deletions

diff --git a/documentation/content/en/books/fdp-primer/doc-build/chapter.adoc b/documentation/content/en/books/fdp-primer/doc-build/chapter.adoc
index 6344581b49..33a4443ae8 100644
--- a/documentation/content/en/books/fdp-primer/doc-build/chapter.adoc
+++ b/documentation/content/en/books/fdp-primer/doc-build/chapter.adoc
@@ -72,6 +72,17 @@ To render the documentation and the website use one of the following examples.
 ....
 ====
 
+[[project-build-example]]
+.Build the entire documentation project
+[example]
+====
+[source,bash]
+....
+% cd ~/doc
+% make -j2
+....
+====
+
 [[doc-build-toolset]]
 == The FreeBSD Documentation Build Toolset
 
@@ -86,24 +97,35 @@ These are the tools used to build and install the FDP documentation.
 [[doc-build-makefile]]
 == Understanding the Makefile in the Documentation Tree
 
-There is only one [.filename]#Makefile# in the [.filename]#documentation# and other in the [.filename]#website#. Both are pretty similar.
+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# take the form of:
+This [.filename]#Makefile# takes the following form:
 
 [source,bash]
 ....
 # Generate the FreeBSD documentation
 #
-# Copyright (c) 2020-2021 The FreeBSD Documentation Project
+# 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
-# compile	-	generate the books TOC and build 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 <.>
 
@@ -111,25 +133,30 @@ PYTHON_CMD =	/usr/local/bin/python3.7 <.>
 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 <.>
 
-all: starting-message generate-books-toc run <.>
-generate: starting-message generate-books-toc build <.>
+.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: <.>
+starting-message: .PHONY <.>
 	@echo ---------------------------------------------------------------
 	@echo                   Building the documentation
 	@echo ---------------------------------------------------------------
 
-generate-books-toc: <.>
+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: <.>
-	${HUGO_CMD} server -D 
+run: .PHONY <.>
+	${HUGO_CMD} server -D
 
-build: <.>
+build: .PHONY <.>
 	${HUGO_CMD} --minify
 ....
 
@@ -137,8 +164,8 @@ build: <.>
 <.> `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.
-<.> `all` target generate the books TOCs and run the documentation in the Hugo local webserver.
-<.> `generate` target generate the books TOCs and build the documentation in the [.filename]#~/doc/documentation/public# folder. The content of this folder should be placed in a HTTP server like nginx.
+<.> `.ORDER` directives are used to ensure multiple make jobs may run without problem.
+<.> `all` target generate the books 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 in a random free port.
@@ -153,43 +180,53 @@ This [.filename]#Makefile# take the form of:
 ....
 # Generate the FreeBSD website
 #
-# Copyright (c) 2020-2021 The FreeBSD Documentation Project
+# 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
-# generate	-	generate the releases.toml and build 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.7 <.>
 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 <.>
-generate: starting-message generate-releases build <.>
 
-starting-message: <.>
+starting-message: .PHONY <.>
 	@echo ---------------------------------------------------------------
 	@echo                   Building the website
 	@echo ---------------------------------------------------------------
 
-generate-releases: <.>
+generate-releases: .PHONY <.>
 	${PYTHON_CMD} ./tools/releases-toml.py -p ./shared/releases.adoc
 
-run: <.>
+run: .PHONY <.>
 	${HUGO_CMD} server -D
 
-build: <.>
-	${HUGO_CMD} --minify
+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.
-<.> `all` target generate the books TOCs and run the website in the Hugo local webserver.
-<.> `generate` target generate the books TOCs and build the website in the [.filename]#~/doc/website/public# folder. The content of this folder should be placed in a HTTP server like nginx.
+<.> `.ORDER` directives are used to ensure multiple make jobs may run without problem.
+<.> `all` target generate the books TOCs, builds the documentation 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 in a random free port.
+<.> `run` runs hugo webserver on a random free port.
 <.> `build` builds the website and puts the result in the [.filename]#~/doc/website/public#.