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

Merge pull request #2029 from infosiftr/finally-some-docs 

A little ♥♥♥ and clarification for the main README
This commit is contained in:
Tianon Gravi 2021-09-09 18:48:19 +00:00 committed by GitHub
parent 2a5aff1ec6 6d56ef8eec
commit 69864c01cf
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 54 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

90
README.md
View File

@ -1,6 +1,6 @@
# What is this?
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.
This repository contains the image documentation for each of the Docker 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), and verified as formatted correctly via GitHub Actions.
@ -62,7 +62,9 @@ After opening your Pull Request the changes will be checked by an automated `mar
Optionally:
- run `./markdownfmt.sh -l myimage` to verify whether format of your markdown files is compliant to `tianon/markdownfmt`. In case you see any file names, markdownfmt detected some issues, which might result in a failed build during continuous integration. run `./markdownfmt.sh -d myimage` to see a diff of changes required to pass.
- run `./markdownfmt.sh -l myimage` to list any files that are non-compliant to [`tianon/markdownfmt`](https://hub.docker.com/r/tianon/markdownfmt).
Any files in the list will result in a failed build during continuous integration.
- run `./markdownfmt.sh -d myimage` to see a diff of changes required to pass.
- 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.
@ -70,15 +72,15 @@ Optionally:
## folder `<image name>`
This is where all the partial and generated files for a given image reside, (ex: `golang/`).
This is where all the partial (e.g. `content.md`) and generated files (e.g. `README.md`) for a given image reside, (e.g. `golang/`). It must match the name of the image used in `docker-library/official-images`.
## `README.md`
This file is generated using `update.sh`.
This file is generated using `update.sh`. Do not commit or edit this file; it is regenerated periodically by a bot.
## `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:
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. The following is a basic layout:
```markdown
# What is XYZ?
@ -93,27 +95,9 @@ This file contains the main content of your image's long description. The basic
// make use of subsections as necessary
```
## `README-short.txt`
## `get-help.md`
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.
This file is an optional override of the default `get-help.md`. This is the content of the "Where to get help" part of the "Quick reference" at the top of the generated README. We recommend linking to the best places for community support like forums, chat rooms, or mailing lists.
## `github-repo`
@ -123,36 +107,68 @@ This file should contain the URL to the GitHub repository for the Dockerfiles th
https://github.com/docker-library/golang
```
## `user-feedback.md`
## `license.md`
This file is an optional override of the default `user-feedback.md` for those repositories with different issue and contributing policies.
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.
```
## `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. Alternatively, a `logo.svg` can be used instead, but only one logo file will apply. To use it within `content.md`, put `%%LOGO%%` as shown above in the basic `content.md` layout.
The image is automatically scaled to a 120 pixel square for the top of the Docker Hub page and Hub search results.
## `maintainer.md`
This file should contain a link to the maintainers of the Dockerfile.
## `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.
## `stack.yml`
This optional file contains a small, working [Compose file for Docker Swarm](https://docs.docker.com/compose/compose-file/compose-file-v3/) showing off how to use the image. To use the `stack.yml`, add `%%STACK%%` to the `content.md` and this will embed the YAML along with a link to directly try it in [Play with Docker](https://labs.play-with-docker.com/).
The file must work via `docker stack deploy` since that is how Play with Docker will launch it, but it is helpful for users to try locally if it works for `docker-compose` as well. Other official images may be referenced within the YAML to demonstrate the functionality of the image, but no images external to the Docker Official Images program may be referenced.
# Files for main Docs repo
## `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). Accepted arguments are which image(s) you want to update or 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. Accepted arguments are which image(s) you want to update or no arguments to update all of them.
This script assumes [`bashbrew`](https://github.com/docker-library/official-images/tree/81e90ca8dcec892ade7eb348cba5a4a5d6851e17/bashbrew) is in your `PATH` (for scraping relevant tag information from the library manifest file for each repository).
## `generate-repo-stub-readme.sh`
## `markdownfmt.sh` and `ymlfmt.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.
## `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.
These two scripts are for verifying the formatting of Markdown (`.md`) and YAML (`.yml`) files, respectively. `markdownfmt.sh` uses the [`tianon/markdownfmt`](https://hub.docker.com/r/tianon/markdownfmt) image and `ymlfmt.sh` uses the [`tianon/ymlfmt`](https://hub.docker.com/r/tianon/ymlfmt) image.
## `.template-helpers/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).
## `.template-helpers/template.md` and `.template-helpers/user-feedback.md`
## `.template-helpers/`
These files are the templates used in building the `<image name>/README.md` file, in combination with the individual image's files.
The scripts and Markdown files in here are used in building an image's `README.md` file in combination with its individual files.
# Scripts unrelated to templates
## `generate-repo-stub-readme.sh`
This is used to generate a simple `README.md` to put in the image's repo. We use this in Git repositories within https://github.com/docker-library to simplify our maintenance, but it is not required for anyone else. Argument is the name of the image, like `golang` and it then outputs the readme to standard out.
## `push.pl` and `push.sh`
These are 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. The `Dockerfile` is used to create a suitable environment for `push.pl`.
# 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/).
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 [Libera.Chat](https://libera.chat/) or open up an issue.

2
push.pl
View File

@ -186,7 +186,7 @@ while (my $repo = shift) { # 'library/hylang', 'tianon/perl', etc
qw( convert -background none -density 1200 -strip -resize 120x120> -gravity center -extent 120x120 ),
$logoToConvert,
$repoLogo120,
) == 0 or die "failed to convert $repoLogoPng into $repoLogo120";
) == 0 or die "failed to convert $logoToConvert into $repoLogo120";
}
}
if (-f $repoLogo120) {