Merge pull request #35 from jhudsl/howardbaek/documentation

Beef up the README

README.md

@@ -2,6 +2,7 @@
 
 This action runs either spelling, url, or quiz format checks in an [OTTR course](https://github.com/jhudsl/OTTR_Template).
 
+
 ## Inputs
 
 ## `check_type`
@@ -49,3 +50,82 @@ with:
   error_min: 0
   gh_pat: secrets.GH_PAT
 ```
+
+
+## main.yml
+
+This GitHub Actions (GHA) workflow, "Testing ottr-reports", performs a series of checks on pull requests made to the main branch and can also be manually triggered using the workflow_dispatch event.
+
+It is composed of four jobs: `get_branch`, `spell-check`, `urls-check`, and `quiz-format`:
+
+1. `get_branch` Job
+
+Purpose: Determines the branch name that triggered the workflow and makes it available for subsequent jobs.
+
+**Steps:**
+1. Executes a shell command to extract the branch name from `GITHUB_REF` environment variable
+2. Stores it in the `GITHUB_OUTPUT` for use in later steps.
+
+
+2. `spell-check` Job
+
+Note: This job waits for the `get_branch` job to complete successfully before starting.
+
+Purpose: Checks spelling in the repository.
+
+Steps: 
+1. Fetches the repository's content 
+2. Uses a custom action to check spelling, configured with parameters like `check_type`, `error_min`, and the branch name extracted in the `get_branch` job.
+3. Displays the path to the spelling report, the contents of the report, and the number of detected errors.
+
+
+3. `urls-check` Job
+
+Purpose: Verifies that URLs in the repository are valid.
+
+Steps:
+1. Fetches the repository's content.
+2. Uses the same custom action for checking, but with the `check_type` set to URLs, and it's configured to allow for a minimum of 0 errors.
+3. Shows the path to the URL check report, its contents, and the error count.
+
+
+4. `quiz-format` Job
+
+Purpose: Checks the formatting of quizzes in the repository.
+
+Steps:
+1. Checks out the repository's content.
+2. Uses the custom action with `check_type` set to `quiz_format`, and similar to URLs check, it's set to tolerate a minimum of 0 errors.
+3. Outputs the path to the quiz format report, its content, and the number of errors detected.
+
+
+## report-maker.yml
+
+This GitHub Actions (GHA) workflow, "Run error checker", runs checks based on specific inputs and handles commenting on pull requests with the results of these checks.
+
+It is composed of two jobs: `status-update` and `error-check`:
+
+1. `status-update` Job
+
+Steps:
+1. Based on the `check_type` input, it sets variables for the error name and ignore file path.
+2. Captures the current time and commit ID for later use 
+3. Uses an external action (`peter-evans/find-comment@v3`) to find an existing comment by github-actions[bot] that includes the specified error name.
+4. If a comment is found, it updates the comment to indicate that the check is being re-run, using the time and commit ID captured earlier.
+
+
+2. `error-check` Job
+
+Similar initial steps as `status-update` job to declare error names based on check_type.
+
+Steps:
+1. Checks out the code from a branch named `preview-${{ github.event.pull_request.number }}`
+2. Executes the actual check using a custom action `jhudsl/ottr-reports@main`
+3. Captures additional details such as the link to the ignore file and the URL for the error report.
+4. Uses an external action (`peter-evans/find-comment@v3`) to find an existing comment by github-actions[bot] that includes the specified error name.
+5. If check failed, a comment is made or updated to indicate the check did not fully run. 
+6. If there are more errors than allowed (error_min), it comments with details about the errors and links to the report. Conversely, if the errors are within the acceptable range, it updates or posts a comment indicating there are no errors.
+7. Commit the report file generated by the checks into a branch. It also counts the number of errors and stores this count for subsequent steps.
+8. Based on the number of errors relative to error_min, different actions are taken. If there are too many errors, it fails the job; otherwise, it acknowledges the acceptable error count.
+9. Comments are made or updated on the pull request to reflect the outcome of the checks, providing feedback directly in the PR discussion.
+