diff --git a/documentation/Makefile b/documentation/Makefile index 3b5c1cfd65..4b594fcdca 100644 --- a/documentation/Makefile +++ b/documentation/Makefile @@ -1,53 +1,53 @@ # Generate the FreeBSD documentation # # 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 # 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 +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 .ifndef HOSTNAME .HOST+=localhost .else .HOST+=$(HOSTNAME) .endif .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 run: starting-message generate-books-toc run-local 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-local: .PHONY ${HUGO_CMD} server -D --baseURL="http://$(.HOST):1313" build: .PHONY ${HUGO_CMD} --minify 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 1d938d89c6..81aaa9be2d 100644 --- a/documentation/content/en/books/fdp-primer/doc-build/chapter.adoc +++ b/documentation/content/en/books/fdp-primer/doc-build/chapter.adoc @@ -1,232 +1,232 @@ --- 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 # # 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.7 <.> +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 # # 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.7 <.> +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#. diff --git a/website/Makefile b/website/Makefile index 2294db8838..4b32bf76d7 100644 --- a/website/Makefile +++ b/website/Makefile @@ -1,48 +1,48 @@ # Generate the FreeBSD website # # 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 # run - serves the built website for local browsing # # The run target uses hugo's built-in webserver to make the built website # available for local browsing. The website 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 +PYTHON_CMD = /usr/local/bin/python3 HUGO_CMD = /usr/local/bin/hugo .ifndef HOSTNAME .HOST+=localhost .else .HOST+=$(HOSTNAME) .endif .ORDER: all run .ORDER: starting-message generate-releases .ORDER: starting-message build .ORDER: generate-releases build all: starting-message generate-releases build run: starting-message generate-releases run-local starting-message: .PHONY @echo --------------------------------------------------------------- @echo Building the website @echo --------------------------------------------------------------- generate-releases: .PHONY ${PYTHON_CMD} ./tools/releases-toml.py -p ./shared/releases.adoc run-local: .PHONY ${HUGO_CMD} server -D --baseURL="http://$(.HOST):1313" build: .PHONY ${HUGO_CMD}