git: 85faabdc47 - main - Update build chapter in FDP
Sergio Carlavilla Delgado
carlavilla at FreeBSD.org
Fri Jan 29 17:21:30 UTC 2021
The branch main has been updated by carlavilla:
URL: https://cgit.FreeBSD.org/doc/commit/?id=85faabdc47119055c9807d1daea33af2eb394de7
commit 85faabdc47119055c9807d1daea33af2eb394de7
Author: Sergio Carlavilla Delgado <carlavilla at FreeBSD.org>
AuthorDate: 2021-01-29 17:20:04 +0000
Commit: Sergio Carlavilla Delgado <carlavilla at FreeBSD.org>
CommitDate: 2021-01-29 17:20:04 +0000
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
---
.../en/books/fdp-primer/doc-build/chapter.adoc | 85 ++++++++++++++++------
1 file 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 at 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 at 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 at 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 at 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#.
More information about the dev-commits-doc-all
mailing list