diff --git a/documentation/Makefile b/documentation/Makefile index 3e63ccef69..3b1a29d9bc 100644 --- a/documentation/Makefile +++ b/documentation/Makefile @@ -1,225 +1,244 @@ # 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 # 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 +# offline use. +# If variable DOC_HTML_ARCHIVE is set, all documents will be +# archived/compressed, and only these files will be kept in the public +# directory. # # 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 # List of languages without book translations ARTICLEONLY_LANGS= bn-bd da ko tr # List of languages without article translations BOOKONLY_LANGS= mn # List of all languages we have content for ALL_LANGUAGES= bn-bd da de el en es fr hu it ja ko mn nl pl pt-br ru tr zh-cn zh-tw LOCALBASE?= /usr/local PYTHON_CMD = ${LOCALBASE}/bin/python3 RUBY_CMD = ${LOCALBASE}/bin/ruby HUGO_CMD = ${LOCALBASE}/bin/hugo HUGO_ARGS?= --verbose --minify HUGO_OFFLINE_ARGS?= --environment offline --verbose --minify ASCIIDOCTOR_CMD= ${LOCALBASE}/bin/asciidoctor ASCIIDOCTORPDF_CMD= ${LOCALBASE}/bin/asciidoctor-pdf .if defined(DOC_LANG) && !empty(DOC_LANG) LANGUAGES= ${DOC_LANG:S/,/ /g} .if ${LANGUAGES:Men} == "" && ${.TARGETS:Mpdf*} == "" && ${.TARGETS:Mhtml*} == "" .warning "Warning: cannot skip 'en'; adding it back" LANGUAGES+= en .endif .else LANGUAGES= ${ALL_LANGUAGES} .endif RUBYLIB = ../shared/lib .export RUBYLIB RUN_DEPENDS= ${PYTHON_CMD} \ ${HUGO_CMD} \ ${LOCALBASE}/bin/asciidoctor \ ${LOCALBASE}/bin/rougify .ifndef HOSTNAME . ifdef BIND .HOST=$(BIND) . else .HOST=localhost . endif .else .HOST=$(HOSTNAME) .endif # 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. SKIP_LANGS= .for a in ${ALL_LANGUAGES} .if ${LANGUAGES:M${a}} == "" SKIP_LANGS+= ${a} .endif .endfor .ORDER: all run .ORDER: requirements .ORDER: starting-message generate-books-toc .ORDER: starting-message build .ORDER: generate-books-toc build all: requirements starting-message generate-books-toc generate-pgpkeys-txt build run: requirements starting-message generate-books-toc generate-pgpkeys-txt run-local # clean does not call pdf-clean as that is a subset of hugo-clean clean: hugo-clean pgp-clean toc-clean requirements: .for dep in ${RUN_DEPENDS} .if !exists(${dep}) @(echo ${dep} not found, please run 'pkg install docproj python3'; exit 1) .endif .endfor requirements-pdf: .if !exists(${LOCALBASE}/bin/asciidoctor-pdf) @(echo ${LOCALBASE}/bin/asciidoctor-pdf not found, please run 'pkg install rubygem-asciidoctor-pdf'; exit 1) .endif starting-message: .PHONY @echo --------------------------------------------------------------- @echo Building the documentation @echo included languages: ${LANGUAGES} @echo excluded languages: ${SKIP_LANGS} @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-books-toc-offline: .PHONY .if !empty(BOOK_LANGS) ${PYTHON_CMD} ./tools/books-toc-parts-creator.py -o -l ${BOOK_LANGS} ${PYTHON_CMD} ./tools/books-toc-creator.py -o -l ${BOOK_LANGS} ${PYTHON_CMD} ./tools/books-toc-figures-creator.py -o -l ${BOOK_LANGS} ${PYTHON_CMD} ./tools/books-toc-tables-creator.py -o -l ${BOOK_LANGS} ${PYTHON_CMD} ./tools/books-toc-examples-creator.py -o -l ${BOOK_LANGS} .endif generate-pgpkeys-txt: static/pgpkeys/pgpkeys.txt static/pgpkeys/pgpkeys.txt: static/pgpkeys/*key ${RUBY_CMD} ./tools/global-pgpkeys-creator.rb run-local: .PHONY HUGO_DISABLELANGUAGES="${SKIP_LANGS}" ${HUGO_CMD} server \ ${HUGO_ARGS} -D $(BIND:D--bind=$(BIND)) --baseURL="http://$(.HOST):1313" build: .PHONY HUGO_DISABLELANGUAGES="${SKIP_LANGS}" ${HUGO_CMD} ${HUGO_ARGS} build-offline: .PHONY HUGO_DISABLELANGUAGES="${SKIP_LANGS}" ${HUGO_CMD} ${HUGO_OFFLINE_ARGS} toc-clean: .PHONY .if !empty(BOOK_LANGS) rm -f $$(${PYTHON_CMD} ./tools/books-toc-parts-creator.py -l ${BOOK_LANGS} -p) rm -f $$(${PYTHON_CMD} ./tools/books-toc-creator.py -l ${BOOK_LANGS} -p) rm -f $$(${PYTHON_CMD} ./tools/books-toc-figures-creator.py -l ${BOOK_LANGS} -p) rm -f $$(${PYTHON_CMD} ./tools/books-toc-tables-creator.py -l ${BOOK_LANGS} -p) rm -f $$(${PYTHON_CMD} ./tools/books-toc-examples-creator.py -l ${BOOK_LANGS} -p) .endif pgp-clean: .PHONY rm -f static/pgpkeys/pgpkeys.txt hugo-clean: .PHONY rm -rf resources public # # PDF targets # Use DOC_LANG to choose the language, e.g., make DOC_LANG="en fr" pdf-books # pdf: pdf-articles pdf-books pdf-books: requirements-pdf generate-books-toc .for _lang in ${BOOK_LANGS} ./tools/asciidoctor.sh books ${_lang} pdf .endfor pdf-articles: requirements-pdf .for _lang in ${ARTICLE_LANGS} ./tools/asciidoctor.sh articles ${_lang} pdf .endfor pdf-clean: pdf-articles-clean pdf-books-clean pdf-books-clean: .for _lang in ${BOOK_LANGS} rm -fr ${.CURDIR}/public/${_lang}/books -rmdir ${.CURDIR}/public/${_lang} .endfor -rmdir ${.CURDIR}/public/ pdf-articles-clean: .for _lang in ${ARTICLE_LANGS} rm -fr ${.CURDIR}/public/${_lang}/articles .if !exists(${.CURDIR}/public/${_lang}/books) rm -fr ${.CURDIR}/public/${_lang} .endif .endfor -rmdir ${.CURDIR}/public # # HTML targets # -html: generate-books-toc-offline build-offline html-clean-global html-clean-articles html-clean-books +html: generate-books-toc-offline build-offline html-clean-global html-clean-articles html-clean-books html-archive html-archive-clean-files html-clean: hugo-clean html-clean-global: rm -fr ${.CURDIR}/public/index.html rm -rf pgpkeys js html-clean-articles: .for _lang in ${ARTICLE_LANGS} rm -fr ${.CURDIR}/public/${_lang}/index.html rm -fr ${.CURDIR}/public/${_lang}/articles/index.html .endfor html-clean-books: .for _lang in ${BOOK_LANGS} rm -fr ${.CURDIR}/public/${_lang}/books/index.html .endfor + +html-archive: +.if defined(DOC_HTML_ARCHIVE) +.for _lang in ${ARTICLE_LANGS} + ./tools/asciidoctor.sh articles ${_lang} archive +.endfor +.for _lang in ${BOOK_LANGS} + ./tools/asciidoctor.sh books ${_lang} archive +.endfor +.endif + +html-archive-clean-files: +.if defined(DOC_HTML_ARCHIVE) + find ${.CURDIR}/public/ ! -name '*.pdf' ! -name '*.tar.gz' -type f -delete + find ${.CURDIR}/public/ -type d -empty -delete +.endif diff --git a/documentation/tools/asciidoctor.sh b/documentation/tools/asciidoctor.sh index 6f33181e25..28924d0b03 100755 --- a/documentation/tools/asciidoctor.sh +++ b/documentation/tools/asciidoctor.sh @@ -1,118 +1,166 @@ #!/bin/sh # # Copyright (c) 2021 Danilo G. Baio # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are met: # # 1. Redistributions of source code must retain the above copyright notice, this # list of conditions and the following disclaimer. # # 2. Redistributions in binary form must reproduce the above copyright notice, # this list of conditions and the following disclaimer in the documentation # and/or other materials provided with the distribution. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED # WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE # DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR # SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER # CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, # OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. # shellcheck disable=SC3043 LOCALBASE="/usr/local" ASCIIDOCTORPDF_CMD="${LOCALBASE}/bin/asciidoctor-pdf" build_pdf() { if [ "$1" = "" ] || [ "$2" = "" ] || [ "$3" = "" ]; then exit 1 fi local doc_type="$1" local doc_lang="$2" local doc_name="$3" local cur_dir_source="content/$doc_lang/$doc_type/$doc_name/" local cur_dir_output="public/$doc_lang/$doc_type/$doc_name/" if [ ! -d "$cur_dir_output" ]; then mkdir -p "$cur_dir_output" fi if [ "$doc_type" = "books" ]; then local asciidoctor_type="book" if [ -f "${cur_dir_source}book.adoc" ]; then local asciidoctor_file_name="book.adoc" else local asciidoctor_file_name="_index.adoc" fi fi if [ "$doc_type" = "articles" ]; then local asciidoctor_type="article" local asciidoctor_file_name="_index.adoc" fi $ASCIIDOCTORPDF_CMD \ -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 \ -r ./shared/lib/cross-document-references-macro.rb \ --doctype="$asciidoctor_type" \ -a skip-front-matter \ - -a lang=${doc_lang} \ + -a lang="$doc_lang" \ -a isonline=1 \ -a env-beastie=1 \ -a pdf-theme=default-with-fallback-font \ -o "${cur_dir_output}${doc_name}_${doc_lang}.pdf" \ "${cur_dir_source}${asciidoctor_file_name}" } # build_epub() +archive() { + if [ "$1" = "" ] || [ "$2" = "" ] || [ "$3" = "" ]; then + exit 1 + fi + + local doc_type="$1" + local doc_lang="$2" + local doc_name="$3" + + if [ -d "public/$doc_lang" ]; then + local pub_dir="public/$doc_lang/$doc_type/$doc_name/" + elif [ -d "public/$doc_type" ]; then + # single language build + local pub_dir="public/$doc_type/$doc_name/" + fi + + if [ -f "${pub_dir}${doc_name}_${doc_lang}.tar.gz" ]; then + rm -f "${pub_dir}${doc_name}_${doc_lang}.tar.gz" + fi + + local source_doc_dir="" + if [ -d "public/source/$doc_type/$doc_name/" ]; then + source_doc_dir="public/source/$doc_type/$doc_name/" + fi + + local image_doc_dir="" + if [ -d "public/images/$doc_type/$doc_name/" ]; then + image_doc_dir="public/images/$doc_type/$doc_name/" + fi + + tar -czf "public/${doc_name}_${doc_lang}.tar.gz" \ + "$pub_dir" \ + public/css/ \ + public/fonts/ \ + public/js/ \ + $source_doc_dir \ + $image_doc_dir + + mv -f "public/${doc_name}_${doc_lang}.tar.gz" "$pub_dir" + +} + + main() { if [ "$1" = "" ] || [ "$2" = "" ] || [ "$3" = "" ]; then echo "Needs parameters (type, language and format)." echo "$0 articles en pdf" exit 1 fi local doc_type="$1" local doc_lang="$2" local doc_format="$3" if [ ! "$doc_type" = "articles" ] && [ ! "$doc_type" = "books" ]; then echo "First parameter needs to be 'articles' or 'books'" exit 1 fi - if [ ! "$doc_format" = "pdf" ]; then - # Default pdf - doc_format="pdf" - fi - - for document in $(find "content/$doc_lang/$doc_type/" -type d -mindepth 1 -maxdepth 1 | awk -F '/' '{ print $4 }' | sort -n); do - if [ "$doc_format" = "pdf" ] && [ "$document" = "pgpkeys" ]; then - continue - fi - - if [ "$doc_format" = "pdf" ]; then - echo "asciidoctor build_pdf: $doc_type $doc_lang $document $doc_format" - build_pdf "$doc_type" "$doc_lang" "$document" - fi - - done + case "$doc_format" in + pdf) + for document in $(find "content/$doc_lang/$doc_type/" -type d -mindepth 1 -maxdepth 1 | awk -F '/' '{ print $4 }' | sort -n); do + if [ "$document" = "pgpkeys" ]; then + continue + fi + echo "asciidoctor build_pdf: $doc_type $doc_lang $document" + build_pdf "$doc_type" "$doc_lang" "$document" + done + ;; + archive) + for document in $(find "content/$doc_lang/$doc_type/" -type d -mindepth 1 -maxdepth 1 | awk -F '/' '{ print $4 }' | sort -n); do + echo "generate archive: $doc_type $doc_lang $document" + archive "$doc_type" "$doc_lang" "$document" + done + ;; + *) + echo "Formats available: archive, pdf" + exit 1 + ;; + esac } main "$@"