From d28df3445851aee0a2502c6f1f5689972f017702 Mon Sep 17 00:00:00 2001
From: Felix Fontein <felix@fontein.de>
Date: Sun, 21 Jan 2024 14:36:51 +0100
Subject: [PATCH] Add documentation.

---
 .../workflows/{yamllint.yml => liniting.yml}  |  0
 README.md                                     | 96 +++++++++++++++++++
 action.yml                                    |  7 +-
 3 files changed, 100 insertions(+), 3 deletions(-)
 rename .github/workflows/{yamllint.yml => liniting.yml} (100%)
 create mode 100644 README.md

diff --git a/.github/workflows/yamllint.yml b/.github/workflows/liniting.yml
similarity index 100%
rename from .github/workflows/yamllint.yml
rename to .github/workflows/liniting.yml
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..16f707e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,96 @@
+# GitHub Action for building Ansible collections
+
+[![Linting](https://github.com/ansible-community/github-action-build-collection/actions/workflows/yamllint.yml/badge.svg)](https://github.com/ansible-community/github-action-build-collection/actions/workflows/nox.yml)
+[![REUSE status](https://api.reuse.software/badge/github.com/ansible-community/github-action-build-collection)](https://api.reuse.software/info/github.com/ansible-community/github-action-build-collection)
+
+A composite GitHub Action that allows to build an Ansible collection artifact in GitHub Actions CI/CD workflows.
+
+
+## Usage
+
+To use the action, add the following step to your workflow file (for example `.github/workflows/build-collection.yml`):
+
+```yaml
+- name: Check out your collection repository
+  uses: actions/checkout@v4
+
+- name: Build collection
+  id: build-collection
+  uses: ansible-community/github-action-build-collection@main
+
+- name: Upload built collection as artifact
+  uses: actions/upload-artifact@v4
+  with:
+    name: my-collection
+    path: ${{ steps.build-collection.outputs.artifact-filename }}
+```
+
+## Options
+
+The follow options can be provided to this GitHub Action.
+
+### `python-version`
+
+The Python version to use for running ansible-core.
+
+**(DEFAULT: `3.12`)**
+
+### `ansible-core-version`
+
+The branch of tag name of ansible-core to install.
+This is assumed to exist in https://github.com/ansible/ansible.
+
+**(DEFAULT: `stable-2.16`)**
+
+### `subdirectory`
+
+The subdirectory in which the collection's sources can be found. Must contain the `galaxy.yml` file.
+
+**(DEFAULT: `.`)**
+
+### `collection-requirements-path`
+
+If provided, the collection's requirements will be written as a Galaxy `requirements.yml` file to this path.
+
+## Outputs
+
+The GitHub Action provides the following outputs that can be used in further workflow steps.
+
+### `collection-full-name`
+
+The collection's full name (namespace.name).
+
+### `collection-name`
+
+The collection's name. For example `ansible.posix`'s name is `posix`.
+
+### `collection-namespace`
+
+The collection's namespace. For example `ansible.posix`'s namespace is `ansible`.
+
+### `collection-version`
+
+The collection's version. Will be set to `0.0.1` if no `version` field is present in `galaxy.yml`.
+
+### `artifact-filename`
+
+Filename of the built collection artifact.
+
+### `artifact-path`
+
+Path to the built collection artifact.
+
+## Bundled shared workflow
+
+This GitHub Action bundles a shared workflow, [build-collection.yaml](https://github.com/ansible-community/github-action-build-collection/blob/main/.github/workflows/build-collection.yml), which allows you to build a collection, and upload the built collection artifact together with its `requirements.yml` file as a GitHub artifact.
+
+```yaml
+jobs:
+  build-collection:
+    name: Build collection artifact
+    permissions:
+      contents: read
+    uses: ansible-community/github-action-build-collection/.github/workflows/build-collection.yml@main
+```
+
+Please check out the workflow for the options it supports, and for which outputs it provides.
diff --git a/action.yml b/action.yml
index 30e3c56..7f8cfa3 100644
--- a/action.yml
+++ b/action.yml
@@ -10,11 +10,12 @@ author: "Felix Fontein (@felixfontein)"
 inputs:
   python-version:
     description: >-
-      The Python version to use.
+      The Python version to use for running ansible-core.
     default: '3.12'
   ansible-core-version:
     description: >-
       The branch of tag name of ansible-core to install.
+      This is assumed to exist in https://github.com/ansible/ansible.
     default: 'stable-2.16'
   subdirectory:
     description: >-
@@ -22,7 +23,7 @@ inputs:
     default: .
   collection-requirements-path:
     description: >-
-      If provided, the collection's requirements will be written as a Galaxy requirements.yml file to this path.
+      If provided, the collection's requirements will be written as a Galaxy `requirements.yml` file to this path.
 outputs:
   collection-full-name:
     description: >-
@@ -38,7 +39,7 @@ outputs:
     value: ${{ steps.collection-metadata.outputs.namespace }}
   collection-version:
     description: >-
-      The collection's version. Will be set to 0.0.1 if no `version` field is present in `galaxy.yml`.
+      The collection's version. Will be set to `0.0.1` if no `version` field is present in `galaxy.yml`.
     value: ${{ steps.collection-metadata.outputs.version }}
   artifact-filename:
     description: >-