Elaborate readme

[vincerubinetti]

I think the readme right now is fairly sparse, and could use elaboration. Even as a dev on the Manubot team, I don't exactly get the full grasp of what this tool is and how to use it from the readme. For example:

1. Linking to the environment variables file to show what parameters the tool can take. In fact, maybe it's better to pull out the comments in that file into a table in the readme; then in env var py file you can refer to the readme?
2. Where and how can this tool be run? Currently there's an example of running it as a python package, but what about running it on GitHub Actions? Even if this repo is just for the python package portion, I think there should be a brief explanation of how it fits into the larger collection of things, e.g. link to the github actions workflow in rootstock.
3. What different ways can the options be configured?
4. Provide recipes/examples instead of linking to unit tests.
5. Linking to the section of models.py where the actual prompts are? And perhaps even extracting the prompt static text somehow to somewhere that's easier to read than in the middle of a long python file? I do see there's some logic going on there that could make this tough, but actually maybe it's better to extract this to a plain text file and have "insert variables" like %KEYWORDS% that get replace()ed, which could also be used by users specifying their own prompts? Maybe there could be a directory with the prompts, allowing the user to add their own just once (in the same place as all the other prompts), and use it with a simple section mapping like for the built-in section types, instead of specifying CUSTOM_PROMPT which seems to get applied to everything automatically.
6. Maybe some kind of minimal docs page auto-generated from the python function comments?
7. Is there any easier way to "install" this into an existing manubot manuscript and run it locally than copying the current example script? Understanding things better now, I think the canonical way you're meant to use it locally is with the manubot ai-revision sub-command? And I guess you wanted to provide an example of using this package directly? If so, this should be spelled out in the readme.

For 2 and 3, I think we should sit down and sketch out the "hierarchy" of things. Because there are a lot of facets to consider:

• multiple contexts where this can run
  • locally as python package
  • locally as manubot sub-command, manubot ai-revision (I wish this was renamed to ai-revise to make it a verb like the other sub-commands, but it's probably too late for that)
  • github actions
• different parts of the toolset
  • this python package as a standalone thing
  • this package "embedded" in the main manubot python package as a sub-command and with its own CLI arguments (I'm kinda confused why this repo's code isn't just directly in the manubot package repo in the ai-revision folder?)
  • manubot rootstock running the manubot sub-command from a github actions workflow with its own set of input boxes
• different ways to config
  • CLI args/flags (e.g. manubot ai-revision --content-directory)
  • env variables
  • func parameters (if using this package directly)
  • yaml file
  • markdown html comments
  • github actions manual workflow run input textboxes
  • in what order to these override each other? will the config options be the same across the board (I hope)?
• different granularities
  • file/section-level
  • "excerpt" level (same file, multiple paragraphs)
  • paragraph-level
• different permanency
  • likely permanent config, like assigning certain sections certain types (e.g., introduction will probably always get the "introduction" type prompt)
  • temporary configs for experimentation (not requiring a commit, and thus quicker, more convenient, and "non-destructive")

I've asked a lot of personal questions above, but not for naught, I think these are things users will also wonder about and should be addressed in the readme.