From 47b32301a691a841f65a55d746d81c4611e90cb1 Mon Sep 17 00:00:00 2001 From: Joe Ferguson Date: Mon, 1 Dec 2014 12:21:52 -0800 Subject: [PATCH 1/2] Add a README.md --- README.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 000000000..ff2812d0c --- /dev/null +++ b/README.md @@ -0,0 +1,87 @@ +# What is this? + +This repository contains the docs for each of the Docker official images. See [docker-library/official-images](https://github.com/docker-library/official-images) for the configuration how the images are built. To see all of the official images go to the [hub](https://registry.hub.docker.com/repos/stackbrew/?&s=alphabetical). + +# How do I add a new image's docs + +- create a folder for my image: `mkdir myimage` +- create a `README-short.txt` (required, 100 char max) +- create a `content.md` (required, 80 col wrap) +- create a `license.md` (required, 80 col wrap) +- add a `logo.png` (recommended) +- edit `update.sh` as needed (see below) +- run `./update.sh myimage` to generate `myimage/README.md` + +# What are all these files? + +## `update.sh` + +This is the main script used to generate the `README.md` files for each image. The generated file is committed along with the files used to generate it (see below on what customizations are available). When a new image is added that is not under the `docker-library` namespace on GitHub, a new entry must be added to the `otherRepos` array in this script. Accepted arguments are which image(s) you want to update and no arguments to update all of them. + +## `push.pl` + +This is used by us to push the actual content of the READMEs to the Docker Hub as special access is required to modify the Hub description contents. + +## `generate-dockerfile-links-partial.sh` + +This script is used by `update.sh` to create the "Supported tags and respective `Dockerfile` links" section of each generated `README.md` from the information in the [official-images `library/` manifests](https://github.com/docker-library/official-images/tree/master/library). + +## `generate-repo-stub-readme.sh` + +This is used to generate a simple `README.md` to put in the image's repo. Argument is the name of the image, like `golang` and it then outputs the readme to standard out. + +## folder `` + +This is where all the partial and generated files for a given image reside, (ex: `golang/`). + +## `README-template.md` and `user-feedback.md` + +These files are the templates used in building the `/README.md` file, in combination with the individual image's files. + +## `/content.md` + +This file contains the main content of your readme. The basic parts you should have are a "What Is" section and a "How To" section. See the doc on [Official Repos](https://docs.docker.com/docker-hub/official_repos/#a-long-description) for more information on long description. The issues and contribution section is generated by the script but can be overridden. The following is a basic layout: + + # What is XYZ? + + // about what the contained software is + + %%LOGO%% + + # How to use this image + + // descriptions and examples of common use cases for the image + // make use of subsections as necessary + +## `/README-short.txt` + +This is the short description for the docker hub, limited to 100 characters in a single line. + +> Go (golang) is a general purpose, higher-level, imperative programming language. + +## `/logo.png` + +Logo for the contained software. Specifications can be found in the docs on [Official Repos](https://docs.docker.com/docker-hub/official_repos/#a-logo) + +## `/license.md` + +This file should contain a link to the license for the main software in the image, wrapped to 80 columns. Here is an example for golang: + + View [license information](http://golang.org/LICENSE) + for the software contained in this image. + +## `/user-feedback.md` + +This file is an optional override of the default `user-feedback.md` for those repositories with different issue and contributing policies. + +## `/mailing-list.md` + +This file is snippet that gets inserted into the user feedback section to provide and extra way to get help, like a mailing list. Here is an example from the Postgres image: + + on the [mailing list](http://www.postgresql.org/community/lists/subscribe/) or + +# Issues and Contributing + +If you would like to make a new Official Image, be sure to follow the [guidelines](https://docs.docker.com/docker-hub/official_repos/) and talk to partners@docker.com. + +Feel free to make a pull request for fixes and improvements to current documentation. For questions or problems on this repo come talk to us via the `#docker-library` IRC channel on [Freenode](https://freenode.net) or open up an issue. From c902ab430336c09aaace205defa7d553391211b2 Mon Sep 17 00:00:00 2001 From: Joe Ferguson Date: Mon, 1 Dec 2014 15:13:36 -0800 Subject: [PATCH 2/2] Flow to 80 columns --- README.md | 63 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 48 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index ff2812d0c..e1755144e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,10 @@ # What is this? -This repository contains the docs for each of the Docker official images. See [docker-library/official-images](https://github.com/docker-library/official-images) for the configuration how the images are built. To see all of the official images go to the [hub](https://registry.hub.docker.com/repos/stackbrew/?&s=alphabetical). +This repository contains the docs for each of the Docker official images. See +[docker-library/official-images](https://github.com/docker-library/official-images) +for the configuration how the images are built. To see all of the official +images go to the +[hub](https://registry.hub.docker.com/repos/stackbrew/?&s=alphabetical). # How do I add a new image's docs @@ -16,31 +20,49 @@ This repository contains the docs for each of the Docker official images. See [ ## `update.sh` -This is the main script used to generate the `README.md` files for each image. The generated file is committed along with the files used to generate it (see below on what customizations are available). When a new image is added that is not under the `docker-library` namespace on GitHub, a new entry must be added to the `otherRepos` array in this script. Accepted arguments are which image(s) you want to update and no arguments to update all of them. +This is the main script used to generate the `README.md` files for each image. +The generated file is committed along with the files used to generate it (see +below on what customizations are available). When a new image is added that is +not under the `docker-library` namespace on GitHub, a new entry must be added to +the `otherRepos` array in this script. Accepted arguments are which image(s) +you want to update and no arguments to update all of them. ## `push.pl` -This is used by us to push the actual content of the READMEs to the Docker Hub as special access is required to modify the Hub description contents. +This is used by us to push the actual content of the READMEs to the Docker Hub +as special access is required to modify the Hub description contents. ## `generate-dockerfile-links-partial.sh` -This script is used by `update.sh` to create the "Supported tags and respective `Dockerfile` links" section of each generated `README.md` from the information in the [official-images `library/` manifests](https://github.com/docker-library/official-images/tree/master/library). +This script is used by `update.sh` to create the "Supported tags and respective +`Dockerfile` links" section of each generated `README.md` from the information +in the [official-images `library/` +manifests](https://github.com/docker-library/official-images/tree/master/library). ## `generate-repo-stub-readme.sh` -This is used to generate a simple `README.md` to put in the image's repo. Argument is the name of the image, like `golang` and it then outputs the readme to standard out. +This is used to generate a simple `README.md` to put in the image's repo. +Argument is the name of the image, like `golang` and it then outputs the readme +to standard out. ## folder `` -This is where all the partial and generated files for a given image reside, (ex: `golang/`). +This is where all the partial and generated files for a given image reside, (ex: +`golang/`). ## `README-template.md` and `user-feedback.md` -These files are the templates used in building the `/README.md` file, in combination with the individual image's files. +These files are the templates used in building the `/README.md` +file, in combination with the individual image's files. ## `/content.md` -This file contains the main content of your readme. The basic parts you should have are a "What Is" section and a "How To" section. See the doc on [Official Repos](https://docs.docker.com/docker-hub/official_repos/#a-long-description) for more information on long description. The issues and contribution section is generated by the script but can be overridden. The following is a basic layout: +This file contains the main content of your readme. The basic parts you should +have are a "What Is" section and a "How To" section. See the doc on [Official +Repos](https://docs.docker.com/docker-hub/official_repos/#a-long-description) +for more information on long description. The issues and contribution section +is generated by the script but can be overridden. The following is a basic +layout: # What is XYZ? @@ -55,33 +77,44 @@ This file contains the main content of your readme. The basic parts you should ## `/README-short.txt` -This is the short description for the docker hub, limited to 100 characters in a single line. +This is the short description for the docker hub, limited to 100 characters in a +single line. > Go (golang) is a general purpose, higher-level, imperative programming language. ## `/logo.png` -Logo for the contained software. Specifications can be found in the docs on [Official Repos](https://docs.docker.com/docker-hub/official_repos/#a-logo) +Logo for the contained software. Specifications can be found in the docs on +[Official Repos](https://docs.docker.com/docker-hub/official_repos/#a-logo) ## `/license.md` -This file should contain a link to the license for the main software in the image, wrapped to 80 columns. Here is an example for golang: +This file should contain a link to the license for the main software in the +image, wrapped to 80 columns. Here is an example for golang: View [license information](http://golang.org/LICENSE) for the software contained in this image. ## `/user-feedback.md` -This file is an optional override of the default `user-feedback.md` for those repositories with different issue and contributing policies. +This file is an optional override of the default `user-feedback.md` for those +repositories with different issue and contributing policies. ## `/mailing-list.md` -This file is snippet that gets inserted into the user feedback section to provide and extra way to get help, like a mailing list. Here is an example from the Postgres image: +This file is snippet that gets inserted into the user feedback section to +provide and extra way to get help, like a mailing list. Here is an example from +the Postgres image: on the [mailing list](http://www.postgresql.org/community/lists/subscribe/) or # Issues and Contributing -If you would like to make a new Official Image, be sure to follow the [guidelines](https://docs.docker.com/docker-hub/official_repos/) and talk to partners@docker.com. +If you would like to make a new Official Image, be sure to follow the +[guidelines](https://docs.docker.com/docker-hub/official_repos/) and talk to +partners@docker.com. -Feel free to make a pull request for fixes and improvements to current documentation. For questions or problems on this repo come talk to us via the `#docker-library` IRC channel on [Freenode](https://freenode.net) or open up an issue. +Feel free to make a pull request for fixes and improvements to current +documentation. For questions or problems on this repo come talk to us via the +`#docker-library` IRC channel on [Freenode](https://freenode.net) or open up an +issue.