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
This commit is contained in:
Sergio Carlavilla Delgado
parent
61850f5a35
commit
85faabdc47
1 changed files with 62 additions and 25 deletions
|
|
@ -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<.>
|
||||
|
||||
starting-message: <.>
|
||||
.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: <.>
|
||||
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 <.>
|
||||
|
||||
all: starting-message generate-releases run <.>
|
||||
generate: starting-message generate-releases build <.>
|
||||
.ORDER: all run<.>
|
||||
|
||||
starting-message: <.>
|
||||
.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: <.>
|
||||
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#.
|
||||
|
|
|
|||
Loading…
Reference in a new issue