Date: Wed, 14 Jul 2021 10:35:34 GMT From: Marc Fonvieille <blackend@FreeBSD.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org Subject: git: 27a51efaa2 - main - documentation/Makefile: Add HTML targets for offline use Message-ID: <202107141035.16EAZYDT045444@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch main has been updated by blackend: URL: https://cgit.FreeBSD.org/doc/commit/?id=27a51efaa2d42b4625214533dba414b3b140e573 commit 27a51efaa2d42b4625214533dba414b3b140e573 Author: Marc Fonvieille <blackend@FreeBSD.org> AuthorDate: 2021-07-14 10:28:49 +0000 Commit: Marc Fonvieille <blackend@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@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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202107141035.16EAZYDT045444>