Skip to content

Utility util readme

Jump to bottom
accetto edited this page Nov 6, 2022 · 6 revisions

Utility util-readme.sh

Version: G3v2

Updated: 2022-11-04

Remark

It is the second version (G3v2) of the project described here.

The previously contained publish command has been removed, because it was not working properly any more. Some changes on the Docker Hub side seemed to be the reason. However, you can always copy-and-pase the content generated by the preview command (the file scrap-readme.md) to the Docker Hub manually.

TL;DR

First prepare the environment. Open a terminal window and change the current directory to utils.

The utility requires the ID of the deployment GitHub Gist, which you can provide as a parameter or by setting the environment variable DEPLOY_GIST_ID:

export DEPLOY_GIST_ID="<deployment-gist-ID>"

Then you can generate the short README files for the Docker Hub:

### PWD = utils/

./util-readme.sh --repo accetto/ubuntu-vnc-xfce-g3 --context=../docker/xfce --gist <deployment-gist-ID> -- preview

./util-readme.sh --repo accetto/ubuntu-vnc-xfce-chromium-g3 --context=../docker/xfce-chromium --gist <deployment-gist-ID> -- preview

./util-readme.sh --repo accetto/ubuntu-vnc-xfce-firefox-g3 --context=../docker/xfce-firefox --gist <deployment-gist-ID> -- preview

### or if the environment variable 'DEPLOY_GIST_ID' has been set

./util-readme.sh --repo accetto/ubuntu-vnc-xfce-g3 --context=../docker/xfce -- preview

./util-readme.sh --repo accetto/ubuntu-vnc-xfce-chromium-g3 --context=../docker/xfce-chromium -- preview

./util-readme.sh --repo accetto/ubuntu-vnc-xfce-firefox-g3 --context=../docker/xfce-firefox -- preview

Then copy-and-paste the content of the generated file scrap-readme.md to the Docker Hub manually.

Introduction

This utility is intended to be used by developers on the local building stage. It is written in the Linux shell script language (bash) and it does not require any additional utilities except the standard ones.

It allows:

  • previewing composed and templated README files before publishing
  • checking the length of the final README files

The utility assumes that it is executed from the folder utils/. In other words, you should switch to the folder utils/ before using it. The default values of some arguments depend on this assumption.

Version and help

The utility has been developed with the help of argbash tool and the image accetto/argbash-docker, so the built-in help and version information are available through the options -h and -v (or --help and --version).

utils> ./util-readme.sh -v
./util-readme.sh v22.11.04
utils> ./util-readme.sh -h
Utility for previewing README files intended for Docker Hub. The prepared files can be manually copy-and-pasted to Docker Hub. The utility should be run from the '/utils' directory.
Usage: ./util-readme.sh [-v|--version] [-h|--help] [--repo <arg>] [--context <arg>] [--readme <arg>] [--template <arg>] [--limit <arg>] [--gist <arg>] [--] [<command>]
        <command>: Command to execute. Available commands:
                 # cleanup - Deletes the previously generated README preview and other helper files.
                 #           This is the default command if both <command> and <repo> are empty.
                 # preview - Generates the README preview file and checks its length.
                 #           This is the default command if <command> is empty, but <repo> is not.
                 # (default: '')
        -v, --version: Prints version
        -h, --help: Prints help
        --repo: Target Docker Hub repository (owner/repo) (default: '')
        --context: Path to the readme files (relative to '/utils', e.g. '../docker/xfce') (default: '')
        --readme: Readme file main part name (default: 'README-dockerhub.md')
        --template: Readme appendix template file name (default: 'readme-append.template')
        --limit: Max. length of the final README file in bytes (max. 25000) (default: '25000')
        --gist: Gist ID containing off-line metadata (e.g. badge endpoints)(alternatively set 'DEPLOY_GIST_ID' environment variable) (no default)

Positional argument command

This is the only positional argument used by the utility. There are two supported commands.

Command cleanup

This command removes the previously generated helper files:

  • scrap-readme.md is the README file preview

This is the default command if no command and --repo values are provided.

This command is also part of the other commands, so it's not necessary to execute it explicitly.

Command preview

This command generates the final README preview and stores it into the preview file scrap-readme.md.

The updated appendix template file scrap-append.tmp may also be generated, but it is automatically removed after using it for composing the final README.

The final README file is a concatenation of the main README part and the optional templated appendix.

The actual length of the final README is compared against the current limit and if it is greater, then an internal variable is set, prohibiting the publishing.

This is the default command if no command value is provided, but the repo option is.

The command uses the following options:

  • repo is the target repository on the Docker Hub
  • context is the path to the README file and the appendix template
  • readme is the name of the file containing the main README part
  • template is the name of the templated appendix file
  • limit is the max. length of the final README file in bytes
  • gist is the GitHub Gist ID containing the metadata, e.g. the badge JSON endpoints

The detailed description of the options is below.

Optional arguments

Option repo

This is the target Docker Hub repository for which to generate the final README file.

The format of this value is owner/repository. The owner and repository values are also used for updating the README appendix template.

This option has no default value.

Option context

This is the path of the folder containing the main README part and the README appendix template. The path is relative to the current directory.

This option has no default value.

Option readme

This is the name of the file containing the main (not templated) part of the final README file.

The default value of this option is README-dockerhub.md.

Option template

This is the name of the file containing the template of the appendix of the final README file.

The appendix template contains badge hyperlinks that contain environment variables ${OWNER}, ${REPO} and ${GIST}. These are replaced by the values provided through the related options repo and gist. The result file is then appended to the main README part to make the final README file.

If an empty string is provided as the template option value, then the whole composing and templating is skipped. The final README file is then identical to the main part defined by the option readme.

The default value of this option is readme-append.template.

Option limit

This option defines the max. length of the final README file in bytes (characters).

It is necessary to watch the README file length, because it is currently limited to 25000 bytes by the Docker Hub.

If the final README file is too long, then its publishing will be prohibited.

The default value of this option is 25000.

Option gist

This is the ID value of the GitHub Gist belonging to the target Docker Hub repository.

The GitHub Gist contains the off-line metadata used by the templated appendix of the README file, e.g. the badge JSON endpoints.

This option has no default value, but it can be provided through the environment variable DEPLOY_GIST_ID.

Usage examples

Composed image README file with template

This is the default use case of composing the final README file for Docker Hub from the main (not templated) part and the templated appendix. The appendix contains the badge links that contain some environment variables, that should be replaced by their current values.

We want to generate the README file for the repository accetto/ubuntu-vnc-xfce-g3, so we set the repo option accordingly.

The README parts are stored in the folder ../docker/xfce (relative to the current directory), so the context option is set to that value.

The names of the main README part and the appendix template files are the default ones. The environment variable DEPLOY_GIST_ID has already been set. The file size limit is the default one.

First we generate the preview file:

utils> ./util-readme.sh --repo accetto/ubuntu-vnc-xfce-g3 --context=../docker/xfce -- preview
Cleanup finished.
Readme preview: ./scrap-readme.md 
Readme length is 7514 bytes, leaving 17486 bytes available (max. 25000).

After checking that everything is correct we can copy-and-paste the content of the generated file scrap-readme.md to the Docker Hub manually.

Image README file without composing

We want to publish the main README file, which belongs to the image accetto/ubuntu-vnc-xfce-g3. This is actually the long README file, which is published on the GitHub. It does not contain any variables that require replacing, but we are not sure about its length.

The target repository is accetto/ubuntu-vnc-xfce-g3.

We have to set the context and the target repository accordingly. We have also to set the correct name of the README file to use. By setting the option template to an empty string we disable composing. The environment variable DEPLOY_GIST_ID has already been set. The file size limit is the default one.

First we generate the preview file:

utils> ./util-readme.sh --repo accetto/ubuntu-vnc-xfce-g3 --context=../docker/xfce --readme=README.md --template="" -- preview
Cleanup finished.
Readme preview: ./scrap-readme.md 
Readme length is 24885 bytes, leaving 115 bytes available (max. 25000).

After checking that everything is correct we can copy-and-paste the content of the generated file scrap-readme.md to the Docker Hub manually.

Default project README file without composing

We want to publish the default project README file to the repository accetto/dev-ubuntu-vnc-xfce-g3. This file is actually the README placeholder, which can published to a new Docker Hub repository, for example.

We have to provide the correct name of the target repository. By setting the context and the readme options we choose the correct README file. By setting the option template to an empty string we disable composing. The environment variable DEPLOY_GIST_ID has already been set. The file size limit is the default one.

First we generate the preview file:

utils> ./util-readme.sh --repo accetto/dev-ubuntu-vnc-xfce-g3 --context=../docker --readme=README.md --template="" -- preview
Cleanup finished.
Readme preview: ./scrap-readme.md 
Readme length is 2288 bytes, leaving 22712 bytes available (max. 25000).

After checking that everything is correct we can copy-and-paste the content of the generated file scrap-readme.md to the Docker Hub manually.

Clone this wiki locally