ttomecek added a new comment to an issue you are following: `` To elaborate on Petr's point a bit: there is some ambiguous documentation about help files in Fedora now. With this issue we would like to:

1. reach consent 2. update the documentation

To be more precise:

Maintainers should include a copy of this help file in the base directory of their images.

Is this sentence about dist-git? Does it mean that image maintainers should (or even have to?) `COPY help.1 /`? I am asking because latest image of mine is doing `COPY ./root/ /`, does it violate the policy?

Container review process contains this sentence: ``` Required files should be:

* Dockerfile * help.md file ```

I don't personally understand whether it's a must-have or should-have. It is also inconsistent with container guidelines because those talk about `help.1` and `README.md`.

I propose to remove the information about help files from the review process document and just have the information in guidelines only. The other thing is that we should reach conclusion on whether there is a mandatory dist-git repo structure. ``

To reply, visit the link below or just reply to this email https://pagure.io/atomic-wg/issue/354

smilner added a new comment to an issue you are following: ``

Container review process contains this sentence: Required files should be:

• Dockerfile
• help.md file

I don't personally understand whether it's a must-have or should-have. It is also inconsistent with container guidelines because those talk about help.1 and README.md.

I totally agree. I believe we should be as specific as we can be to give a consistent help system to users. Being explicit on the help guide would go a long way.

In my mind there should be two files:

- ``README.md``: gives a quick description/overview. This is more open ended. - ``help.md``: gives ``man`` like information. This should be strict.

The structure of ``help.md`` should be based of a standard template that is filled out for the specific image. ``

To reply, visit the link below or just reply to this email https://pagure.io/atomic-wg/issue/354

dustymabe added a new comment to an issue you are following: ``

Is this sentence about dist-git? Does it mean that image maintainers should (or even have to?) COPY help.1 /? I am asking because latest image of mine is doing COPY ./root/ /, does it violate the policy?

I think as long as the file makes it into the root of the image it doesn't matter how it gets there. I think the typical way to do it would be to take the file from dist-git and copy it into the image.

In general, I do want to make sure we don't make things to complicated for new users. We definitely need consistent guidelines, but I wonder about making there be too many fields in required help files.

Can I get someone to summarize exactly what the new proposed guidelines would be (highlighting proposed changes and explicitly stating any text to remove)?

``

To reply, visit the link below or just reply to this email https://pagure.io/atomic-wg/issue/354

smilner added a new comment to an issue you are following: `` ## README.md

A quick description and general human helpful text. Similar to what would be in a repo

## help.md

### Original Help [Container Guidelines: Help File](https://fedoraproject.org/wiki/Container:Guidelines#Help_File)

Defined:

- Volumes: map of volume name: description - Ports: map of port_number: description - Documentation: Link to online documentation - Requirements: Human friendly text describing what the container needs to run - Configuration: Human friendly text describing information on how the container is configured

### Stricter Help Mimics ``man`` style:

- Header: -- IMAGE_SHORT_NAME(1) -- Person who wrote the document -- Last updated - Name: IMAGE_SHORT_NAME: IMAGE_SHORT_DESCRIPTION - Description: IMAGE_LONG_DESCRIPTION - Usage: Command(s) that can be used to install the container (IE: docker example, atomic example) - Environment Variables: Two width table listing available ``Variable Name`` and ``Description`` - Security Implications: -- Ports: Ports opened/used by the container (maps to Original Help's Ports) -- Volumes: Volumes used by the container (maps to Original Help's Volumes) - See Also: Further reading (maps to Documentation of the Original Help)

### Example and Untested Template ``` - {{ IMAGE_NAME|upper }}(1) Container Image Pages - {{ IMAGE_AUTHOR }} - {{ IMAGE_DOC_DATE }}

# NAME {{ IMAGE_NAME }} - {{ IMAGE_SHORT_DESCRIPTION}}

# DESCRIPTION {{ IMAGE_LONG_DESCRIPTION }}

# USAGE {{ IMAGE_USAGE }}

# ENVIRONMENT VARIABLES

The image recognizes the following environment variables that you can set during initialization be passing `-e VAR=VALUE` to the Docker run command.

| Variable name | Description | | :----------------------- | ----------------------------------------------------------- | {% for _name, _description in IMAGE_ENVIRONMENT_VARIABLES.iteritems() %} | `{{ _name|upper }}` | {{ _description}} | {% endfor %}

# SECURITY IMPLICATIONS

## Ports | Port Container | Port Host | Description | | :----------------- | -----------|-------------------------------| {% for _ports, _description in IMAGE_PORTS %} | {{ _port[0] }} | {{ _port[1] }} | {{ _description}} | {% endfor %}

## Volumes | Volume Container | Volume Host | Description | | :----------------- | -----------|-------------------------------| {% for _vols, _description in IMAGE_PORTS %} | {{ _vols[0] }} | {{ _vols[1] }} | {{ _description}} | {% endfor %}

# SEE ALSO {{ IMAGE_SEE_ALSO }} ``` ``

To reply, visit the link below or just reply to this email https://pagure.io/atomic-wg/issue/354

phracek added a new comment to an issue you are following: `` Issue go-md2man is closed. Transformation tables from MD to ROFF works properly. ``

To reply, visit the link below or just reply to this email https://pagure.io/atomic-wg/issue/354

jberkus added a new comment to an issue you are following: `` so is help.md required? We have images which are basically library components. Should they have this file as well? ``

To reply, visit the link below or just reply to this email https://pagure.io/atomic-wg/issue/354

jberkus added a new comment to an issue you are following: `` So are you suggesting that FLIBS should have the capability of genating files based on --help and/or existing man pages? That would be ideal.

If we ask the submitter to do it, that has the dual issues of (a) extra work and (b) not being kept up to date. ``

To reply, visit the link below or just reply to this email https://pagure.io/atomic-wg/issue/354

jberkus added a new comment to an issue you are following: `` Well, that's a bit of a dillema. If there's manual editing involved, then it's One More Thing To Keep Up To Date, which means it won't be.

What I'm suggesting is that we should allow automatic conversion as an alternative, even if it doesn't adhere to the format. ``

To reply, visit the link below or just reply to this email https://pagure.io/atomic-wg/issue/354

phracek added a new comment to an issue you are following: `` I would prefer some kind of templating, like if it is possible to generate some information from `man pages` I will vote for it. Something like this.

`help.md.template` will contain specific issues like security warnings, environment variable, mount points and stuff like that. `help.md` itself can be generated like `man2md` and append `help.md.template` which is not so hard to keep up2date. ``

To reply, visit the link below or just reply to this email https://pagure.io/atomic-wg/issue/354

walters added a new comment to an issue you are following: `` I like the idea of having in-container help, but personally one of the things I *love* about github is the fact that it renders `README.md` files so prominently. I also find myself often wanting to look at the "source" for our containers; I may not want our exact container build, but I want to do something similar or use a different base image. So we could do the same with https://src.fedoraproject.org/ ? (Which really needs a browsable UI for just containers or just modules) ``

To reply, visit the link below or just reply to this email https://pagure.io/atomic-wg/issue/354

phracek added a new comment to an issue you are following: `` The structure defined by @smilner is fine from my point of view. But some digging. I guess, IMAGE_NAME, IMAGE_AUTHOR and IMAGE_DATE should start with `%` instead of `-`.

One more question. Where the help file should be stored in dist-git? In dist-git root directory or in `help` directory? ``

To reply, visit the link below or just reply to this email https://pagure.io/atomic-wg/issue/354

mattdm added a new comment to an issue you are following: `` I don't know if this got lost because I changed topic, but if you have `README.md` at the top level of dist.git, this will be displayed on https://src.fedoraproject.org/. See for example

https://src.fedoraproject.org/container/tools

Now, maybe this should differ from the in-container `help.md` and be more focused on contributor/developer information. But I kind of think they could be the same in most cases.

``

To reply, visit the link below or just reply to this email https://pagure.io/atomic-wg/issue/354

smilner added a new comment to an issue you are following: `` I started working a bit on the generation utility. Any ideas for decent names? Naming is the hardest part :-) ``

To reply, visit the link below or just reply to this email https://pagure.io/atomic-wg/issue/354

smilner added a new comment to an issue you are following: `` @jberkus thanks for the suggestions. I think ``helpgen`` is overloaded. There is a Python library and a company with that name. However, nothing came up quickly searching for ``image-helpgen``. I'll run with that for now. ``

To reply, visit the link below or just reply to this email https://pagure.io/atomic-wg/issue/354

smilner added a new comment to an issue you are following: `` I'll be doing some clean up on the code and then, if there is no more feedback I'll make a release of the tool and open a tracking issue for the next steps. ``

To reply, visit the link below or just reply to this email https://pagure.io/atomic-wg/issue/354

dustymabe added a new comment to an issue you are following: ``

Tagged a release: https://github.com/ashcrow/image-helpgen/releases/tag/1.0

straight to 1.0 :). I like it. ``

To reply, visit the link below or just reply to this email https://pagure.io/atomic-wg/issue/354

phracek added a new comment to an issue you are following: `` image-helpgen looks awesome. I am glad we decided, `help.1` will be present in image at location `/`. Now we will include some sanity checks into `MTF` (https://github.com/fedora-modularity/meta-test-family) or into `conu`(https://github.com/fedora-modularity/conu/) and detect whether help page contains proper information.

``

To reply, visit the link below or just reply to this email https://pagure.io/atomic-wg/issue/354

The status of the issue: `help.md file for each container` of project: `atomic-wg` has been updated to: Closed as Fixed by dustymabe.

https://pagure.io/atomic-wg/issue/354