git: 27a51efaa2 - main - documentation/Makefile: Add HTML targets for offline use
Marc Fonvieille
blackend at FreeBSD.org
Wed Jul 14 10:35:34 UTC 2021
The branch main has been updated by blackend:
URL: https://cgit.FreeBSD.org/doc/commit/?id=27a51efaa2d42b4625214533dba414b3b140e573
commit 27a51efaa2d42b4625214533dba414b3b140e573
Author: Marc Fonvieille <blackend at FreeBSD.org>
AuthorDate: 2021-07-14 10:28:49 +0000
Commit: Marc Fonvieille <blackend at FreeBSD.org>
CommitDate: 2021-07-14 10:28:49 +0000
documentation/Makefile: Add HTML targets for offline use
Addition of various HTML targets allowing the build of books, articles
with the choice of the language. For example, to build both en_US and
fr_FR books, use:
make DOC_LANG="en fr" html-books
Documents are installed in documentation/public/lang/. Targets to clean
the builds are also available.
The produced files do not include some metadatas, they are intended for
offline use.
Reviewed by: ceri
Differential Revision: https://reviews.freebsd.org/D30718
---
documentation/Makefile | 198 +++++++++++++++++++++++++++++++++++++++++++------
1 file changed, 174 insertions(+), 24 deletions(-)
diff --git a/documentation/Makefile b/documentation/Makefile
index 7cbb8cec4d..3ccfc6ca7b 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -9,6 +9,8 @@
# clean - removes generated files
# run - serves the built documentation site for local browsing
# pdf - build PDF versions of the articles and books.
+# html - build HTML versions of the articles and books for
+# offline use
#
# 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
@@ -19,6 +21,8 @@ MAINTAINER=carlavilla at FreeBSD.org
# List of languages without book translations
ARTICLEONLY_LANGS= bd da ko tr
+# List of languages without article translations
+BOOKONLY_LANGS= mn
# List of all languages we have content for
ALL_LANGUAGES= bd da de el en es fr hu it ja ko mn nl pl pt-br ru tr zh-cn zh-tw
@@ -29,11 +33,12 @@ PYTHON_CMD = ${LOCALBASE}/bin/python3
RUBY_CMD = ${LOCALBASE}/bin/ruby
HUGO_CMD = ${LOCALBASE}/bin/hugo
HUGO_ARGS?= --verbose --minify
+ASCIIDOCTOR_CMD= ${LOCALBASE}/bin/asciidoctor
ASCIIDOCTORPDF_CMD= ${LOCALBASE}/bin/asciidoctor-pdf
-
+SED_CMD = /usr/bin/sed
.if defined(DOC_LANG) && !empty(DOC_LANG)
LANGUAGES= ${DOC_LANG:S/,/ /g}
-.if ${LANGUAGES:Men} == "" && ${.TARGETS:Mpdf*} == ""
+.if ${LANGUAGES:Men} == "" && ${.TARGETS:Mpdf*} == "" && ${.TARGETS:Mhtml*} == ""
.warning "Warning: cannot skip 'en'; adding it back"
LANGUAGES+= en
.endif
@@ -60,13 +65,19 @@ RUN_DEPENDS= ${PYTHON_CMD} \
.HOST=$(HOSTNAME)
.endif
-# Strip the languages without articles from the list of languages we
+# Strip the languages with only articles from the list of languages we
# will use to build books.
BOOK_LANGS= ${LANGUAGES}
.for a in ${ARTICLEONLY_LANGS}
BOOK_LANGS:= ${BOOK_LANGS:N${a}}
.endfor
+# Strip the languages with only books from the list of languages we
+# will use to build articles.
+ARTICLE_LANGS= ${LANGUAGES}
+.for a in ${BOOKONLY_LANGS}
+ARTICLE_LANGS:= ${ARTICLE_LANGS:N${a}}
+.endfor
# Take the list of all languages, and take out the ones we have been
# asked for. We'll feed this to hugo.
@@ -105,11 +116,13 @@ starting-message: .PHONY
@echo ---------------------------------------------------------------
generate-books-toc: .PHONY
+.if !empty(BOOK_LANGS)
${PYTHON_CMD} ./tools/books-toc-parts-creator.py -l ${BOOK_LANGS}
${PYTHON_CMD} ./tools/books-toc-creator.py -l ${BOOK_LANGS}
${PYTHON_CMD} ./tools/books-toc-figures-creator.py -l ${BOOK_LANGS}
${PYTHON_CMD} ./tools/books-toc-tables-creator.py -l ${BOOK_LANGS}
${PYTHON_CMD} ./tools/books-toc-examples-creator.py -l ${BOOK_LANGS}
+.endif
generate-pgpkeys-txt: static/pgpkeys/pgpkeys.txt
@@ -143,18 +156,14 @@ hugo-clean: .PHONY
pdf: pdf-articles pdf-books
pdf-books-target:
-.for _lang in ${LANGUAGES:S|,| |g}
-.if exists(${.CURDIR}/content/${_lang}/books/)
-TMP += ${.CURDIR}/content/${_lang}/books/*/
-.endif
+.for _lang in ${BOOK_LANGS}
+TMP+= ${.CURDIR}/content/${_lang}/books/*/
.endfor
BOOKSDIR != echo ${TMP}
pdf-articles-target:
-.for _lang in ${LANGUAGES:S|,| |g}
-.if exists(${.CURDIR}/content/${_lang}/articles/)
+.for _lang in ${ARTICLE_LANGS}
TTMP += ${.CURDIR}/content/${_lang}/articles/*/
-.endif
.endfor
ARTICLESDIR != echo ${TTMP}
@@ -231,31 +240,172 @@ pdf-books-clean: pdf-books-target toc-clean
.for _curpdf in ${BOOKSDIR}
rm -f ${.CURDIR}/public${_curpdf:S|^${.CURDIR}/content||}book.pdf
.endfor
-.for _lang in ${LANGUAGES:S|,| |g}
+.for _lang in ${BOOK_LANGS}
rm -fr ${.CURDIR}/public/${_lang}/books
-.if !exists(${.CURDIR}/public/${_lang}/articles)
- rm -fr ${.CURDIR}/public/${_lang}
+ -rmdir ${.CURDIR}/public/${_lang}
+.endfor
+ -rmdir ${.CURDIR}/public/
+
+#
+# HTML targets
+# Use DOC_LANG to choose the language, e.g., make DOC_LANG="en fr" html-books
+#
+html: html-articles html-books
+
+html-books-target:
+.for _lang in ${BOOK_LANGS}
+TMPH += ${.CURDIR}/content/${_lang}/books/*/
+.endfor
+BOOKSDIR != echo ${TMPH}
+
+html-articles-target:
+.for _lang in ${ARTICLE_LANGS}
+TTMPH += ${.CURDIR}/content/${_lang}/articles/*/
+.endfor
+ARTICLESDIR != echo ${TTMPH}
+
+html-books: html-books-target generate-books-toc
+
+# Books build
+#
+.for _curhtml in ${BOOKSDIR}
+ @mkdir -p ${.CURDIR}/public${_curhtml:S|^${.CURDIR}/content||}
+.if exists(${_curhtml}book.adoc)
+ ${ASCIIDOCTOR_CMD} \
+ -B ${.CURDIR}/ \
+ -r ./shared/lib/man-macro.rb \
+ -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 linkcss -a copycss=${.CURDIR}/themes/beastie/static/css/docbook.css -a stylesheet=docbook.css -a stylesdir=../../css \
+ -a iconfont-remote! -a iconfont-name=font-awesome-min \
+ -o ${.CURDIR}/public${_curhtml:S|^${.CURDIR}/content||}book.html \
+ ${_curhtml}book.adoc
+.if exists(${.CURDIR}/static/images/books/${_curhtml:H:T})
+ @mkdir -p ${.CURDIR}/public${_curhtml:S|^${.CURDIR}/content||:H:H:H}/images/books/
+ cp -R ${.CURDIR}/static/images/books/${_curhtml:H:T}/ \
+ ${.CURDIR}/public${_curhtml:S|^${.CURDIR}/content||:H:H:H}/images/books/${_curhtml:H:T}/
+ ${SED_CMD} -i '' -e "s|../../../../images|../../images|g" \
+ ${.CURDIR}/public${_curhtml:S|^${.CURDIR}/content||}book.html
.endif
+.else
+# some books use _index.adoc as main document
+ ${ASCIIDOCTOR_CMD} \
+ -B ${.CURDIR}/ \
+ -r ./shared/lib/man-macro.rb \
+ -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 linkcss -a copycss=${.CURDIR}/themes/beastie/static/css/docbook.css -a stylesheet=docbook.css -a stylesdir=../../css \
+ -a iconfont-remote! -a iconfont-name=font-awesome-min \
+ -o ${.CURDIR}/public${_curhtml:S|^${.CURDIR}/content||}book.html \
+ ${_curhtml}_index.adoc
+.if exists(${.CURDIR}/static/images/books/${_curhtml:H:T})
+ @mkdir -p ${.CURDIR}/public${_curhtml:S|^${.CURDIR}/content||:H:H:H}/images/books/
+ cp -R ${.CURDIR}/static/images/books/${_curhtml:H:T}/ \
+ ${.CURDIR}/public${_curhtml:S|^${.CURDIR}/content||:H:H:H}/images/books/${_curhtml:H:T}/
+ ${SED_CMD} -i '' -e "s|../../../../images|../../images|g" \
+ ${.CURDIR}/public${_curhtml:S|^${.CURDIR}/content||}book.html
+.endif
+.endif
+.if !exists(${.CURDIR}/public${_curhtml:S|^${.CURDIR}/content||:H:H:H}/fonts/)
+ mkdir -p ${.CURDIR}/public${_curhtml:S|^${.CURDIR}/content||:H:H:H}/fonts/
+ cp -R ${.CURDIR}/themes/beastie/static/fonts/ \
+ ${.CURDIR}/public${_curhtml:S|^${.CURDIR}/content||:H:H:H}/fonts/
+ cp ${.CURDIR}/themes/beastie/static/css/font-awesome-min.css \
+ ${.CURDIR}/public${_curhtml:S|^${.CURDIR}/content||:H:H:H}/css/
+.endif
+.endfor
+
+html-articles: html-articles-target
+
+# Articles build
+.for _curhtml in ${ARTICLESDIR}
+ @mkdir -p ${.CURDIR}/public${_curhtml:S|^${.CURDIR}/content||}
+ ${ASCIIDOCTOR_CMD} \
+ -B ${.CURDIR}/ \
+ -r ./shared/lib/man-macro.rb \
+ -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=article \
+ -a skip-front-matter \
+ -a linkcss -a copycss=${.CURDIR}/themes/beastie/static/css/docbook.css -a stylesheet=docbook.css -a stylesdir=../../css \
+ -a iconfont-remote! -a iconfont-name=font-awesome-min \
+ -o ${.CURDIR}/public${_curhtml:S|^${.CURDIR}/content||}article.html \
+ ${_curhtml}_index.adoc
+.if exists(${.CURDIR}/static/source/articles/${_curhtml:H:T})
+ cp -R ${.CURDIR}/static/source/articles/${_curhtml:H:T}/ \
+ ${.CURDIR}/public${_curhtml:S|^${.CURDIR}/content||}
+.endif
+.if exists(${.CURDIR}/static/images/articles/${_curhtml:H:T})
+ @mkdir -p ${.CURDIR}/public${_curhtml:S|^${.CURDIR}/content||:H:H:H}/images/articles/
+ cp -R ${.CURDIR}/static/images/articles/${_curhtml:H:T}/ \
+ ${.CURDIR}/public${_curhtml:S|^${.CURDIR}/content||:H:H:H}/images/articles/${_curhtml:H:T}/
+ ${SED_CMD} -i '' -e "s|../../../images|../../images|g" \
+ ${.CURDIR}/public${_curhtml:S|^${.CURDIR}/content||}article.html
+.endif
+.if !exists(${.CURDIR}/public${_curhtml:S|^${.CURDIR}/content||:H:H:H}/fonts/)
+ mkdir -p ${.CURDIR}/public${_curhtml:S|^${.CURDIR}/content||:H:H:H}/fonts/
+ cp -R ${.CURDIR}/themes/beastie/static/fonts/ \
+ ${.CURDIR}/public${_curhtml:S|^${.CURDIR}/content||:H:H:H}/fonts/
+ cp ${.CURDIR}/themes/beastie/static/css/font-awesome-min.css \
+ ${.CURDIR}/public${_curhtml:S|^${.CURDIR}/content||:H:H:H}/css/
+.endif
+.endfor
+
+html-clean: html-resources-clean html-articles-clean html-books-clean
+
+html-resources-clean:
+.for _lang in ${LANGUAGES}
+ rm -fr ${.CURDIR}/public/${_lang}/css
+ rm -fr ${.CURDIR}/public/${_lang}/fonts
+ rm -fr ${.CURDIR}/public/${_lang}/images
+.endfor
+
+html-books-clean: html-books-target toc-clean
+.for _curhtml in ${BOOKSDIR}
+ rm -f ${.CURDIR}/public${_curhtml:S|^${.CURDIR}/content||}book.html ${_curhtml}toc*.adoc
+ -rmdir ${.CURDIR}/public${_curhtml:S|^${.CURDIR}/content||}
+.endfor
+.for _lang in ${BOOK_LANGS}
+ rm -fr ${.CURDIR}/public/${_lang}/books
+ rm -fr ${.CURDIR}/public/${_lang}/images/books
+ -rmdir ${.CURDIR}/public/${_lang}
+.endfor
+ -rmdir ${.CURDIR}/public
+
+html-articles-clean: html-articles-target
+.for _curhtml in ${ARTICLESDIR}
+ rm -f ${.CURDIR}/public${_curhtml:S|^${.CURDIR}/content||}article.html
+ -rmdir ${.CURDIR}/public${_curhtml:S|^${.CURDIR}/content||}
+.endfor
+.for _lang in ${ARTICLE_LANGS}
+ rm -fr ${.CURDIR}/public/${_lang}/articles
+ rm -fr ${.CURDIR}/public/${_lang}/images/articles
+ -rmdir ${.CURDIR}/public/${_lang}
.endfor
- @if [ -d ${.CURDIR}/public/ ]; then \
- if [ -z "`ls -A ${.CURDIR}/public/`" ]; then \
- rm -fr ${.CURDIR}/public; \
- fi; \
- fi
+ -rmdir ${.CURDIR}/public
pdf-articles-clean: pdf-articles-target
.for _curpdf in ${ARTICLESDIR}
rm -f ${.CURDIR}/public${_curpdf:S|^${.CURDIR}/content||}article.pdf
.endfor
-.for _lang in ${LANGUAGES:S|,| |g}
+.for _lang in ${ARTICLE_LANGS}
rm -fr ${.CURDIR}/public/${_lang}/articles
.if !exists(${.CURDIR}/public/${_lang}/books)
rm -fr ${.CURDIR}/public/${_lang}
.endif
.endfor
- @if [ -d ${.CURDIR}/public/ ]; then \
- if [ -z "`ls -A ${.CURDIR}/public/`" ]; then \
- rm -fr ${.CURDIR}/public; \
- fi; \
- fi
+ -rmdir ${.CURDIR}/public
More information about the dev-commits-doc-all
mailing list