docker-library
/
docs
mirror of https://github.com/docker-library/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update README.md

This commit is contained in:
wglambert 2020-10-06 12:36:54 -07:00 committed by GitHub
parent 2fadaff09b
commit cc27ce248c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 67 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

130
README.md
View File

@ -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:/
<!-- AUTOGENERATED TOC -->
# 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 `<image name>`
# 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 `<image name>/README.md` file, in combination with the individual image's files.
## folder `<image name>`
This is where all the partial and generated files for a given image reside, (ex: `golang/`).
## `<image name>/README.md`
This file is generated using `update.sh`.
## `<image name>/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
```
## `<image name>/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.
## `<image name>/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.
## `<image name>/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.
```
## `<image name>/maintainer.md`
This file should contain a link to the maintainers of the Dockerfile.
## `<image name>/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
```
## `<image name>/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/).