From owner-dev-commits-doc-all@freebsd.org Fri Jan 29 17:21:30 2021 Return-Path: Delivered-To: dev-commits-doc-all@mailman.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.nyi.freebsd.org (Postfix) with ESMTP id 11C4E4F35FB for ; Fri, 29 Jan 2021 17:21:30 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4DS3zG04MVz3Qwh; Fri, 29 Jan 2021 17:21:30 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id E57492679E; Fri, 29 Jan 2021 17:21:29 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 10THLTHi022030; Fri, 29 Jan 2021 17:21:29 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 10THLTVB022029; Fri, 29 Jan 2021 17:21:29 GMT (envelope-from git) Date: Fri, 29 Jan 2021 17:21:29 GMT Message-Id: <202101291721.10THLTVB022029@gitrepo.freebsd.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org From: Sergio Carlavilla Delgado Subject: git: 85faabdc47 - main - Update build chapter in FDP MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: carlavilla X-Git-Repository: doc X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 85faabdc47119055c9807d1daea33af2eb394de7 Auto-Submitted: auto-generated X-BeenThere: dev-commits-doc-all@freebsd.org X-Mailman-Version: 2.1.34 Precedence: list List-Id: Commit messages for all branches of the doc repository List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 29 Jan 2021 17:21:30 -0000 The branch main has been updated by carlavilla: URL: https://cgit.FreeBSD.org/doc/commit/?id=85faabdc47119055c9807d1daea33af2eb394de7 commit 85faabdc47119055c9807d1daea33af2eb394de7 Author: Sergio Carlavilla Delgado AuthorDate: 2021-01-29 17:20:04 +0000 Commit: Sergio Carlavilla Delgado 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 # # 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 # # 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#.