From cc27ce248cde3fb5b9c0c0308a09a2375975506a Mon Sep 17 00:00:00 2001 From: wglambert Date: Tue, 6 Oct 2020 12:36:54 -0700 Subject: [PATCH 1/2] Update README.md --- README.md | 130 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 67 insertions(+), 63 deletions(-) diff --git a/README.md b/README.md index 52fb627f7..e1ff880c5 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ This repository contains the image documentation for each of the official images. See [docker-library/official-images](https://github.com/docker-library/official-images) for more information about the program in general. -All Markdown files here are run through [tianon's fork of `markdownfmt`](https://github.com/tianon/markdownfmt) (only forked to add some smaller-diff preference and minor DockerHub-compatibility changes), and verified as formatted correctly via GitHub Actions. +All Markdown files here are run through [tianon's fork of `markdownfmt`](https://github.com/tianon/markdownfmt), and verified as formatted correctly via GitHub Actions. - [![GitHub CI status badge](https://img.shields.io/github/workflow/status/docker-library/docs/GitHub%20CI/master?label=GitHub%20CI)](https://github.com/docker-library/docs/actions?query=workflow%3A%22GitHub+CI%22+branch%3Amaster) - [![library update.sh status badge](https://img.shields.io/jenkins/s/https/doi-janky.infosiftr.net/job/docs/job/library.svg?label=Automated%20library%20update.sh)](https://doi-janky.infosiftr.net/job/docs/job/library/) @@ -43,6 +43,12 @@ All Markdown files here are run through [tianon's fork of `markdownfmt`](https:/ +# How do I update an image's docs + +Edit the `content.md` for an image; not the `README.md` as it's auto-generated from the contents of the other files in that repo. To see the changes to the `README.md`, run `./update.sh myimage` from the repo root, but do not add the `README.md` changes to your pull request. See also `markdownfmt.sh` point [below](#how-do-i-add-a-new-images-docs). + +After opening your Pull Request the changes will be checked by an automated `markdownfmt.sh` before it can be merged. A common issue is incorrect spacing such as with two lines missing an empty line between them (double-spaced) + # How do I add a new image's docs - create a folder for my image: `mkdir myimage` @@ -59,11 +65,68 @@ Optionally: - run `./update.sh myimage` to generate `myimage/README.md` for manual review of the generated copy. **Note:** do not actually commit the `README.md` file; it is automatically generated/committed before being uploaded to Docker Hub. -# How do I update an image's docs +# Files related to an image's docs -To update `README.md` for a specific image do not edit `README.md` directly. Please edit `content.md` or another appropriate file within the folder. To see the changes, run `./update.sh myimage` from the repo root, but do not add the `README.md` changes to your pull request. See also `markdownfmt.sh` point [above](#how-do-i-add-a-new-images-docs). +## folder `` -# What are all these files? +This is where all the partial and generated files for a given image reside, (ex: `golang/`). + +## `README.md` + +This file is generated using `update.sh`. + +## `content.md` + +This file contains the main content of your image's long description. 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: + +```markdown +# 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. While there are not hard rules on formatting, most existing logos are square or landscape and stay within a few hundred pixels of width. + +## `license.md` + +This file should contain a link to the license for the main software in the image. Here is an example for `golang`: + +```markdown +View [license information](http://golang.org/LICENSE) for the software contained in this image. +``` + +## `maintainer.md` + +This file should contain a link to the maintainers of the Dockerfile. + +## `github-repo` + +This file should contain the URL to the GitHub repository for the Dockerfiles that become the images. The file should be in a single line ending in a newline with no extraneous whitespace. Only one GitHub repo per image repository is supported. It is used in generating links. Here is an example for `golang`: + +```text +https://github.com/docker-library/golang +``` + +## `user-feedback.md` + +This file is an optional override of the default `user-feedback.md` for those repositories with different issue and contributing policies. + +# Files for main Docs repo ## `update.sh` @@ -87,65 +150,6 @@ This script is used by `update.sh` to create the "Supported tags and respective These files are the templates used in building the `/README.md` file, in combination with the individual image's files. -## folder `` - -This is where all the partial and generated files for a given image reside, (ex: `golang/`). - -## `/README.md` - -This file is generated using `update.sh`. - -## `/content.md` - -This file contains the main content of your image's long description. 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: - -```markdown -# 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. While there are not hard rules on formatting, most existing logos are square or landscape and stay within a few hundred pixels of width. - -## `/license.md` - -This file should contain a link to the license for the main software in the image. Here is an example for `golang`: - -```markdown -View [license information](http://golang.org/LICENSE) for the software contained in this image. -``` - -## `/maintainer.md` - -This file should contain a link to the maintainers of the Dockerfile. - -## `/github-repo` - -This file should contain the URL to the GitHub repository for the Dockerfiles that become the images. The file should be in a single line ending in a newline with no extraneous whitespace. Only one GitHub repo per image repository is supported. It is used in generating links. Here is an example for `golang`: - -```text -https://github.com/docker-library/golang -``` - -## `/user-feedback.md` - -This file is an optional override of the default `user-feedback.md` for those repositories with different issue and contributing policies. - # 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/). From 0985a4907c14d95bf0ba4e87299e259a10e43070 Mon Sep 17 00:00:00 2001 From: wglambert Date: Tue, 6 Oct 2020 12:58:29 -0700 Subject: [PATCH 2/2] Update README.md Co-authored-by: Tianon Gravi --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e1ff880c5..8663b8d76 100644 --- a/README.md +++ b/README.md @@ -47,7 +47,7 @@ All Markdown files here are run through [tianon's fork of `markdownfmt`](https:/ Edit the `content.md` for an image; not the `README.md` as it's auto-generated from the contents of the other files in that repo. To see the changes to the `README.md`, run `./update.sh myimage` from the repo root, but do not add the `README.md` changes to your pull request. See also `markdownfmt.sh` point [below](#how-do-i-add-a-new-images-docs). -After opening your Pull Request the changes will be checked by an automated `markdownfmt.sh` before it can be merged. A common issue is incorrect spacing such as with two lines missing an empty line between them (double-spaced) +After opening your Pull Request the changes will be checked by an automated `markdownfmt.sh` before it can be merged. A common issue is incorrect spacing such as with two lines missing an empty line between them (double-spaced). # How do I add a new image's docs