Create command line tools to automate documentation

[xsebek]

It would be nice to have either a separate executable or a new parameter to generate documentation.

Some ideas:

• We have nice cheatsheets on the Wiki that are hard to keep up to date. Generate those markdown tables from code.
  • Commands (name, type, capability, description) Generate command table #531
  • Capabilities (name, install, commands, description)
  • Entities (character, name, capabilities, properties, portable)
  • Recipes (in, out, required, time)
• Recipe dependencies graph Add generator for recipe dependencies #476
• Editor keywords Generate editor keywords #526

[xsebek]

Also, there are the identifier lists in editors/ that I did not update in a while 😅

• VS Code: swarm.tmLanguage.json

  {
  "name": "keyword.operator",
  "match": "(<|>|==|<=|>=|!=|=|;|<-|-|\\+|\\*|\\^|\\$|/(?![/|*]))"
  },
  {
  "name": "keyword.other",
  "match": "\\b(?i)(noop|wait|selfdestruct|move|turn|grab|place|give|install|make|has|count|drill|build|salvage|reprogram|say|log|view|appear|create|whereami|blocked|scan|upload|ishere|whoami|random|run|if|inl|inr|case|fst|snd|force|return|try|raise|not)\\b"
  }

• Emacs: swarm-mode.el

  (x-builtins '("if" "run" "return" "try" "raise" "force" "fst" "snd"))
  (x-commands
  '("noop" "wait" "selfdestruct" "move" "turn" "grab" "place" "give"
    "install" "make" "build" "salvage" "reprogram"
    "say" "log" "view" "appear" "create" "getx" "gety"
    "blocked" "scan" "upload" "ishere" "whoami"
    "random" "not"
    "left" "right" "back" "forward" "north" "south" "east" "west" "down"
    ))

  There is even a nice note: 🗒️

  ;; We should figure out how to autogenerate these, so we don't have
  ;; to edit the emacs mode every time we add new commands.

[xsebek]

@TristanCacqueray here is my first attempt at the recipe tree:

I will play with Graphviz settings a bit and then I will push the branch 😉

[xsebek]

We should figure out how to use vty terminal mocking or some other way to produce a text representation of the UI - this would be useful to draw recipes but also for testing and documentation.

[xsebek]

I think I will resume this next so that we can keep the whole Wiki up to date.

Making the recipe graph more useful is a separate problem, that I will finish later. It involves:

• Add optional upgrades field to entities #480 (will clean up the backward arrows)
• consider installed devices and inventory separately - I worked on this in WIP: tweak recipe graph #659 but got stuck

[xsebek]

How to render recipes:

• renderWidget: https://hackage.haskell.org/package/brick-1.4/docs/Brick-Main.html#v:renderWidget
• picImage: https://hackage.haskell.org/package/vty-5.37/docs/Graphics-Vty-Picture.html#v:picImage
• ???
• mockTerminal: https://hackage.haskell.org/package/vty-5.37/docs/Graphics-Vty-Output-Mock.html
• ???

Honestly I am not sure how to get just simple text.

[byorgey]

Good question. We should ask @jtdaugherty.

[xsebek]

@byorgey I created an upstream issue for it:

• Mock render Widgets jtdaugherty/brick#405

I wonder if there are other Widgets we would like to print.

---

However, I would like to close this issue and come back to the other improvements later. 🙂