add target for building the documentation locally

Author: nuest

.dockerignore

@@ -0,0 +1 @@
+*

.gitignore

@@ -0,0 +1 @@
+*.pdf

Makefile

@@ -92,7 +92,18 @@ clean:
 	docker ps -a | grep o2r | awk '{print $1}' | xargs docker rm -f
 	docker images | grep o2r | awk '{print $3}' | xargs docker rmi --force
 
-release:
+build_documentation:
+	rm *.pdf
+	docker build --tag docbuilder --file etc/Dockerfile.documentations .
+	docker run -it -v $(CURDIR)/architecture:/doc:rw docbuilder make build pdf 
+	docker run -it -v $(CURDIR)/o2r-web-api:/doc:rw docbuilder  make build pdf 
+	docker run -it -v $(CURDIR)/erc-spec:/doc:rw     docbuilder make build pdf_tinytex
+	mv architecture/site/*.pdf .
+	mv erc-spec/*.pdf .
+	mv o2r-web-api/*.pdf .
+	echo "ERC, architecture, and web API documentation created, see files PDF files in the project root directory"
+
+release: build_documentation
 	git clone --recursive https://github.com/o2r-project/reference-implementation
 	# TODO build all images, export them to files
 

README.md

@@ -166,6 +166,13 @@ docker volume ls
 docker volume inspect reference-implementation_o2r_test_storage
 ```
 
+## Read documentation
+
+This repository also contains specification and documentation projects.
+These documentations are created in Markdown format and can be rendered to HTML and PDF documents using the make target `build_documentation`, which relies on a local `Dockerfile` for the rendering runtime environment.
+The PDF files are moved to the project root directory.
+The HTML files can be found in the respective projects in the `site` directory.
+
 ## Reproducibility
 
 This repository serves the goal to make the developments of the o2r project reproducible, not only by running the reference implementation (see above) but also by creating an archivable package of the software.

etc/Dockerfile.documentations

@@ -0,0 +1,44 @@
+#
+# A Dockerfile for an environment to build the documentation contained in this repository
+#
+
+FROM rocker/verse
+
+# System dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+  python3-pip \
+  python3-setuptools \
+  # next one needed by one of the tex packages
+  xzdec \
+  # next one needed for untaring wkhtmltox
+  xz-utils \
+  libssl1.0-dev
+
+# ERC spec, see erc-spec/.travis.yml
+
+# need newer pandoc
+RUN wget https://github.com/jgm/pandoc/releases/download/2.1.1/pandoc-2.1.1-linux.tar.gz \
+  && tar -xvzf pandoc*.tar.gz --strip-components 1 -C /usr/local/
+
+RUN tlmgr init-usertree \
+  && tlmgr install xcolor mdframed needspace
+RUN pip3 install --upgrade pip \
+  && pip3 install \
+  mkdocs \
+  pymdown-extensions \
+  mkdocs-pandoc \
+  pandoc-latex-admonition \
+  git+https://github.com/o2r-project/mkdocs-combine.git
+
+# architecture, see architecture/.travis.yml
+RUN pip3 install mkdocs mkdocs-cinder markdown-include
+RUN apt-get update && apt-get install -y --no-install-recommends \
+  xfonts-base xfonts-75dpi
+RUN wget https://github.com/wkhtmltopdf/wkhtmltopdf/releases/download/0.12.4/wkhtmltox-0.12.4_linux-generic-amd64.tar.xz \
+  && tar -xvf wkhtmltox-0.12.4_linux-generic-amd64.tar.xz \
+  && mv wkhtmltox/bin/wkhtmltopdf /usr/bin/wkhtmltopdf
+
+VOLUME /doc
+WORKDIR /doc
+
+USER 1000