Docker based workflow for docs

Development
1

Hi everyone!

We've recently added some things to the docs repo that I wanted to talk about. The goal for this post would be to get some of you to try it and get feedback :wink:

Now there's a Dockerfile in the repo that builds a Docker image capable of running all the Python tools we use to check and build the docs, including PDF generation. The Docker image has also a new task that detects changes on source files and rebuilds the docs automatically (only the parts that have changed) while serving them in a development HTTP server.

The README file explains in detail how to build and use this Docker image, but here's a quick start:

  1. Install Docker
  2. Build the Docker image with docker build -t odk-docs .
  3. Run any task in the Makefile with ./run-task.sh TASKNAME (or `.\run-task.bat TASKNAME if you're on Windows)

The new tasks that watch for changes, rebuild the docs, and serve the docs in a development server are odk1-autobuild, and odk2-autobuild.

6 Likes
2

I still wonder if this actually simplifies things for non-tech/non-coding authors — I hope so, but I think we'll have to see what kind of feedback we get from new contributors. (The first time I tried using Docker I was utterly mystified.)

But a totally separate thing I really like about this is:
It provides a platform for future expansion of our tool chain into non-Python things when needed.

Last year we tried to add some screenshot automation which was ultimately fruitless, partly because of the difficulty of getting the right tools set up locally. And our Python-based spell checking through Sphinx is... a bit shaky, as it includes a defunct package in the dependency tree. Having this Docker container as the starting point for local work means we can expand our tools without adding more burden to contributors.

2 Likes
3

Thanks for your feedback, @adammichaelwood!

I agree with you on the possibilities of expanding the toolset that having a container brings us :slight_smile:

I'd love to hear about @DEskinazi's experience with the Docker tools. I think she's the first user of the Docker based toolset.

4

@ggalmazor I liked using the Docker container. It was the easiest time I've had setting up a dev environment.

1 Like
5

Hi, I'm keen to try this, does Docker work on any other version of Windows other than Windows 10 Pro?

6

Hi, @rfletch0! I've tried this on Windows 10 Pro, but it should work on any Windows version where Docker can be installed.

7

My personal laptop has Win10 Home and my work one has Win10 'Education' (plus I am probably restricted from installing things on it anyway). I don't think you can install it on Win10 home, though some people in the forum might have been able to with Docker Toolbox instead?

I think I will try Ubuntu to get around this, a VM or perhaps dual boot kind of thing.

1 Like
8

Hi, @rfletch0! It looks like you're right and Windows Home users need to use the Docker Toolbox alternative, which is based on VirtualBox instead of Hyper-V technology.

This means that working in ODK Docs with the Docker tools we've prepared could be slower for you. Sorry about that! It would be great to know how it goes for you, though.

If it's too slow, you could always set up your Python environment following the contributing guide.

9

By the way, if you're hitting the error about VT-X/AMD-v, you would need to ensure that you have enabled the virtualization technologies on your computer's BIOS.