8750cad450
Currently '/usr/local/bin/python3.7' is used as the value of PYTHON_CMD. Right now this works because 3.7 is the default version of Python 3 in the ports tree. However, at some point in the future, this will be undoubtedly be changed. It is also possible that users already might be building versions newer than the default port/package, which needs to be an supported as well. In addition, the FDP recommends installing the 'python3' package. This meta port/package depends on the default version of python, and automatically creates a symlink to the default version. With all this in mind, use '/usr/local/bin/python3' is used as the value of PYTHON_CMD, since this means that the instructions will work irrespective of which version is assigned.
232 lines
7.2 KiB
Text
232 lines
7.2 KiB
Text
---
|
|
title: Chapter 5. The FreeBSD Documentation Build Process
|
|
prev: books/fdp-primer/structure
|
|
next: books/fdp-primer/asciidoctor-primer
|
|
---
|
|
|
|
[[doc-build]]
|
|
= The FreeBSD Documentation Build Process
|
|
:doctype: book
|
|
:toc: macro
|
|
:toclevels: 1
|
|
:icons: font
|
|
:sectnums:
|
|
:sectnumlevels: 6
|
|
:source-highlighter: rouge
|
|
:experimental:
|
|
:skip-front-matter:
|
|
:xrefstyle: basic
|
|
:relfileprefix: ../
|
|
:outfilesuffix:
|
|
:sectnumoffset: 5
|
|
|
|
toc::[]
|
|
|
|
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.
|
|
|===
|
|
|
|
To render the documentation and the website use one of the following examples.
|
|
|
|
[[documentation-build-example]]
|
|
.Build the documentation
|
|
[example]
|
|
====
|
|
[source,bash]
|
|
....
|
|
% cd ~/doc/documentation
|
|
% make
|
|
....
|
|
====
|
|
|
|
[[website-build-example]]
|
|
.Build the website
|
|
[example]
|
|
====
|
|
[source,bash]
|
|
....
|
|
% cd ~/doc/website
|
|
% make
|
|
....
|
|
====
|
|
|
|
[[project-build-example]]
|
|
.Build the entire documentation project
|
|
[example]
|
|
====
|
|
[source,bash]
|
|
....
|
|
% cd ~/doc
|
|
% make -j2
|
|
....
|
|
====
|
|
|
|
[[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,bash]
|
|
....
|
|
# 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 <.>
|
|
|
|
.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
|
|
|
|
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,bash]
|
|
....
|
|
# 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 <.>
|
|
|
|
.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
|
|
|
|
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#.
|