252 lines
7.9 KiB
Text
252 lines
7.9 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.
|
|
|===
|
|
|
|
[[doc-build-rendering-html]]
|
|
=== Rendering to html
|
|
|
|
To render the documentation and the website to `html` use one of the following examples.
|
|
|
|
[[documentation-build-example]]
|
|
.Build the documentation
|
|
[example]
|
|
====
|
|
[source,shell]
|
|
....
|
|
% cd ~/doc/documentation
|
|
% make
|
|
....
|
|
====
|
|
|
|
[[website-build-example]]
|
|
.Build the website
|
|
[example]
|
|
====
|
|
[source,shell]
|
|
....
|
|
% cd ~/doc/website
|
|
% make
|
|
....
|
|
====
|
|
|
|
[[project-build-example]]
|
|
.Build the entire documentation project
|
|
[example]
|
|
====
|
|
[source,shell]
|
|
....
|
|
% cd ~/doc
|
|
% make -j2
|
|
....
|
|
====
|
|
|
|
[[doc-build-rendering-pdf]]
|
|
=== Rendering to pdf
|
|
|
|
To generate a document in `pdf` format use this command.
|
|
In this example the English Handbook will be used.
|
|
In order to export the document correctly all the extensions should be passed used the `-r` argument.
|
|
|
|
[[document-pdf-example]]
|
|
.Build the entire documentation project
|
|
[example]
|
|
====
|
|
[source,shell]
|
|
....
|
|
asciidoctor-pdf -r ./shared/lib/man-macro.rb -r ./shared/lib/git-macro.rb -r ./shared/lib/packages-macro.rb -r ./shared/lib/inter-document-references-macro.rb -r ./shared/lib/sectnumoffset-treeprocessor.rb --doctype=book -a skip-front-matter -a pdf-theme=./themes/default-pdf-theme.yml content/en/books/handbook/book.adoc
|
|
....
|
|
====
|
|
|
|
[[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,shell]
|
|
....
|
|
# 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,shell]
|
|
....
|
|
# 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#.
|