2

It seems like there are two ways to add documentation to a docker image:

You can add a readme.md in the root folder (where your docker file is located) and this is meant to be parsed by the dockerhub automated build system.

The second way is by using the manifest https://docs.docker.com/docker-hub/publish/publish/#prepare-your-image-manifest-materials But the documentation doesn't really explain well how to annotate the manifest file for an image. Also it looks like the manifest command is considered experimental.

What is the recommended way of documenting a docker image?

Personally i prefer not having to add documentation when the container is being built, i would much rather a file in the source control. However the md file method seems to have minimal support.

ta32
  • 131
  • 1
  • 8
  • the readme.md is the general practice used not only by dockerhub, but also by most git(hub) project. What do you mean by `minimal support` ? – William Chong Jan 09 '19 at 06:15
  • It only works if you use the docker hub automated build. https://stackoverflow.com/questions/29134275/how-to-push-a-docker-image-with-readme-file-to-docker-hub you have to manually attached the readme file if you push the image using a CI tool. – ta32 Jan 09 '19 at 06:21

1 Answers1

1

Most modern container registries (like Dockerhub, Quay, Harbor) have a webinterface that can render and display documentation in Markdown format. When you do automatic builds on Dockerhub from a Github repo, the git repo's README.md can get automatically synced to the repo on Docker Hub. If you build your images locally (or via a CI runner) and push them to Docker Hub you could also push the README file using the docker-pushrm tool. It also supports other container registries than Dockerhub.

Chris
  • 567
  • 6
  • 24