Merge pull request linux-kernel-labs#151 from tavip/lkt-docker-docs

Add support for building documentation via docker
thallett · Mar 4, 2020 · 5231d1b · 5231d1b
2 parents db1dd30 + f9efbb3
commit 5231d1b
Show file tree

Hide file tree

Showing 6 changed files with 66 additions and 9 deletions.
diff --git a/Documentation/sphinx/ditaa.py b/Documentation/sphinx/ditaa.py
@@ -202,7 +202,18 @@ def setup(app):
                  #latex=(latex_visit_ditaa, None),
                  )
     app.add_directive('ditaa', Ditaa)
-    app.add_config_value('ditaa', 'ditaa', 'html')
-    app.add_config_value('ditaa_args', [], 'html')
+
+    try:
+        ditaa_cmd = os.environ['SPHINX_DITAA_CMD']
+    except:
+        ditaa_cmd = 'ditaa'
+
+    try:
+        ditaa_arg = os.environ['SPHINX_DITAA_ARG'].split(':')
+    except:
+        ditaa_arg = []
+
+    app.add_config_value('ditaa', ditaa_cmd , 'html')
+    app.add_config_value('ditaa_args', ditaa_arg, 'html')
     app.add_config_value('ditaa_log_enable', True, 'html')
     app.connect('doctree-read', on_doctree_resolved)
diff --git a/Documentation/teaching/index.rst b/Documentation/teaching/index.rst
@@ -24,14 +24,22 @@ Computers, University POLITEHNICA of Bucharest.
 
 You can get the latest version at http://github.com/linux-kernel-labs.
 
-To get started build the documentation from the sources:
+To get started build the documentation from the sources after
+installing docker-compose on you host:
 
 .. code-block:: c
    
-   cd tools/teaching && make docs
+   cd tools/teaching && make docker-docs
 
 then point your browser at **Documentation/output/labs/index.html**.
 
+Alternatively, you can build directly on the host (see
+tools/labs/docs/Dockerfile for dependencies):
+
+.. code-block:: c
+   
+   cd tools/teaching && make docs
+
 .. toctree::
    :caption: Lectures
 

diff --git a/tools/labs/Makefile b/tools/labs/Makefile
@@ -31,8 +31,11 @@ copy: $(YOCTO_IMAGE)
 	sudo umount $(TEMPDIR)
 	rmdir $(TEMPDIR)
 
+docker-docs:
+	cd docs && docker-compose build
+	cd docs && docker-compose run docs-build bash -c "cd /linux/tools/labs && make docs"
+
 docs:
-	pip install --user -r requirements.txt
 	$(MAKE) -C $(KDIR) DOCBOOKS= SPHINXDIRS="teaching" htmldocs
 	$(MAKE) -C $(KDIR) BUILDDIR=$(KDIR)/Documentation/output/slides DOCBOOKS= SPHINXDIRS="teaching" slides
 	for i in $(KDIR)/Documentation/output/slides/teaching/lectures/*.html; do name=$$(basename $$i .html); cp $$i $(KDIR)/Documentation/output/teaching/lectures/$$name-slides.html; done
@@ -45,4 +48,4 @@ clean::
 clean_skels:
 	rm -rf skels
 
-.PHONY: skels build copy docs clean clean_skels
+.PHONY: skels build copy docs docker-docs clean clean_skels
diff --git a/tools/labs/docs/Dockerfile b/tools/labs/docs/Dockerfile
@@ -0,0 +1,26 @@
+FROM ubuntu:18.04
+
+RUN apt-get update
+RUN apt-get install -y software-properties-common
+RUN apt-get install -y sudo
+RUN apt-get install -y make
+RUN apt-get install -y git
+RUN apt-get install -y python
+RUN apt-get install -y python-pip
+RUN apt-get install -y ditaa
+RUN apt-get install -y graphviz
+RUN pip install Sphinx==1.6.7 sphinx_rtd_theme hieroglyph==1.0
+# append new packages here, to minimize docker rebuild time
+RUN rm -rf /var/lib/apt/lists/*
+
+RUN useradd -ms /bin/bash ubuntu && adduser ubuntu sudo && echo -n 'ubuntu:ubuntu' | chpasswd
+
+# Enable passwordless sudo for users under the "sudo" group
+RUN sed -i.bkp -e \
+      's/%sudo\s\+ALL=(ALL\(:ALL\)\?)\s\+ALL/%sudo ALL=NOPASSWD:ALL/g' \
+      /etc/sudoers
+
+USER ubuntu
+WORKDIR /home/ubuntu/
+
+ENV PATH ${PATH}:/home/ubuntu/.local
diff --git a/tools/labs/docs/docker-compose.yml b/tools/labs/docs/docker-compose.yml
@@ -0,0 +1,12 @@
+version: '3'
+services:
+  docs-build:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    volumes:
+      - ../../../:/linux
+    environment:
+      # workaround for binfmt_misc support in containers
+      - SPHINX_DITAA_CMD=jexec
+      - SPHINX_DITAA_ARG=/usr/bin/ditaa
diff --git a/tools/labs/requirements.txt b/tools/labs/requirements.txt