Docker Community Forums

Share and learn in the Docker community.

Incrementally rebuild of Docker Documentation isn't happening

#1

I’m trying to understand Docker better and thought the documentation might be a fun place to start. That is, the https://docs.docker.com/ website is created in a docker container which is available on Github. But it doesn’t work as documented, for me.

According to https://github.com/docker/docker.github.io/blob/master/README.md I should be able to view and edit the documentation locally via docker-compose. Specifically, “The container runs in the background and incrementally rebuilds the site each time a file changes.”

When I run the 3 commands provided at https://github.com/docker/docker.github.io/blob/master/README.md#staging-the-docs, I can see the docs at http://localhost:4000. But the “incremental rebuild” feature doesn’t work for me. I am able to edit the content, but my changes only appear after rebuilding the whole image.

Has anyone used the incrementally rebuild feature, for the Docker Docs? Ideas about what I might be missing?

#2

I’m no Docker expert.

But having tried this, I can confidently concluded that the readme is flat-out wrong. There are 3 options listed under “Staging the docs,” all problematic & confusing.

The first option does not “incrementally rebuild the site.” The Docker file uses the builder pattern to create a final image free of unneeded dependencies. All the building (markdown to html conversion) is done by jekyll in the “build” image. The second “finished” image has only the static HTML and nginx to serve it up.

The second option seems incomplete. It downloads one repo from Git but does not appear to invoke _scripts/fetch-upstream-resources.sh to get the other sources.

The third option appears to be a variation on the first. It has 2 steps but the first is invalid. This doesn’t matter, because it isn’t needed: the second step is sufficient. Like the first option, there is no incremental rebuild. Actually, with this option, I don’t see how you could make ANY change to the generated docs.

In short: uggh