README.md: Basic documentation on usage

README.md

@@ -0,0 +1,109 @@
+# Status Broadcast System (sbs)
+This is only a test.
+
+`sbs` looks at data from Jira, formats it, combines it with a prompt which can be fed into
+an LLM for creating status.
+
+
+## Usage
+### Top Level
+```
+usage: sbs [-h] {jql,csv} ...
+
+Turns Jira output into a Gemini prompt to generate status
+
+positional arguments:
+  {jql,csv}   commands
+    jql       API call to Jira to pull data
+    csv       Read an exported CSV file from Jira
+
+options:
+  -h, --help  show this help message and exit
+```
+
+### jql
+`jql` is what most people will be looking for. It takes a JQL query and Jira API endpoint and pulls the data.
+
+```
+usage: sbs jql [-h] [-q QUERY] [-e ENDPOINT] [-t TOKEN] [-p PROMPT] [-i] mapping output
+
+positional arguments:
+  mapping               Mapping file for Jira Account=Name
+  output                The file to write
+
+options:
+  -h, --help            show this help message and exit
+  -q, --query QUERY     Text or @file of the jql query to use
+  -e, --endpoint ENDPOINT
+                        Jira API endpoint
+  -t, --token TOKEN     Access token for the Jira API
+  -p, --prompt PROMPT   Text or @file prompt to use
+  -i, --ignore-unknowns Ignores issues that don't have a known assignee
+```
+
+### csv
+`csv` is a less used command used for those who don't have API access to their Jira instance. It looks at an exported CSV file from Jira as it's data.
+```
+usage: sbs csv [-h] [-p PROMPT] [-i] csvfile mapping output
+
+positional arguments:
+  csvfile               Path to the CSV file to read
+  mapping               Mapping file for Jira Account=Name
+  output                The file to write
+
+options:
+  -h, --help            show this help message and exit
+  -p, --prompt PROMPT   Text or @file prompt to use
+  -i, --ignore-unknowns Ignores issues that don't have a known assignee
+```
+
+## Example
+
+### JQL From Source
+We will ignore unassigned tickets, load a prompt from the file myprompt.txt, load a Jira query from the file myquery.txt, use mappingfile.txt as our mapping file and output the results to outputfile.txt.
+
+Since we are using the jql datasource we'll provide it the API endpoint and our access token.
+```
+$ python3 sbs/cli.py jql \
+  -i \
+  -p @myprompt.txt \
+  -q @myquery.txt \
+  mappingfile.txt \
+  outputfile.txt \
+  -e https://issues.redhat.com/rest/api/2 \
+  -t <TOKEN>
+```
+
+### CVS From Source
+We'll give it a prompt on the command line, use mappingfile.txt as our mapping file and output the results to outputfile.txt.
+
+Since we are using the csv datasource we'll provide it the name of the file we exported from Jira.
+```
+$ python3 sbs/cli.py csv \
+  -p "Summarize the following as markdown. Limit each bullet point to a maximum of two sentences."
+  jira_export.csv \
+  mappingfile.txt \
+  outputfile.txt
+```
+
+## mapping
+The mapping file is a simple key=value file seperated by newlines which maps a Jira username to a human name. It's used to make the output used in the prompt more natural for human reading.
+
+**Note**: malformed lines are ignored and the farthest left `=` is used as the seperator.
+
+### Format
+```
+key=value\n
+key=value\n
+key=value\n
+...
+```
+
+### Example mapping File
+```
+$ cat mapping_file.txt
+hyamamo=Himari Yamamoto
+cosmic_coder=Ricardo Ruiz
+metalHEAD42@example.com=Bo Smith
+$
+```