feat(core): add document resource type

[michael-johnston]

This PR adds a new resource type, document, for storing markdown or html docs that describe spaces, operations or combinations thereof.

Create with ado create document -f DOCUMENT.YAML. Read with ado get document $RESOURCEID. A document can have multiple related resources. It's not required that it has any - for example a document containing a report about the entire project at a point in time should not have to list every single space and operation, and there is no "project" resource.

Example document yaml

metadata:
  name: Example operation report
  description: Summary report for an operation
contentType: "markdown"
content: |
  # Operation report

  This is an example document resource.
relatedResources:
  - id: operation-test-12345678
     role: parent

The relatedResources is a list of dictionaries. The dicts have to keys

• id (the id of the related resource)
• role - either parent or child.

ado describe document will

• for markdown, render the content field using rich (when redirected to a file, rich handles it)
• for html, write the content field html (when redirected to a file, the same is done)

#925

[AlessandroPomponio]

From just the description, I wonder whether this design will lead to more of the same problems that we already have for Datacontainers. As it stands, Datacontainers store their content in the resources table and can be very large (we have examples of datacontainers from sft-trainer which exceed 18MB), ballooning the whole table up and slowing down retrieval.

In general, as well, storing byte-like objects in a stringified format in a JSON/text column seems like an antipattern. I would think about only storing references to BLOBs and having a dedicated table for those. Later on in the future we could also take advantage of it to slim down datacontainers

[michael-johnston]

@AlessandroPomponio We could simplify this and remove the attachments functionality for initial implementation. Add it back later if needed/when we decided how to store the attachments (i.e. link instead of raw data, where the raw data goes).

[AlessandroPomponio]

Sounds good!

[AlessandroPomponio]

The PR description says this is also meant for HTML reports. If we keep it to markdown only, though, we could also have a describe command that uses rich's Markdown renderer to render and print the document to the terminal.

This PR is also missing updating the ado cli reference doc

[michael-johnston]

The PR description says this is also meant for HTML reports. If we keep it to markdown only, though, we could also have a describe command that uses rich's Markdown renderer to render and print the document to the terminal.

Yes I did think of this and it was originally markdown. However then Daniele or Vassilis was showing me that bob was creating HTML reports with graphical elements and I thought we should store them.

I mean we could have it also id html and describe open a brokers.

It would be good to have the describe for markdown in any case as reading the reports as human is not easy as is.

[michael-johnston]

If implemented describe for markdown and html, also discriminating behaviour between tty and no tty

[michael-johnston]

So this the next steps

• Ensure the relationships are added to the db
• Remove isatty branching as rich removes its terminal annotations on detecting the redirect already
• Change html behaviour just to print the html - either to terminal or file
  • human readable description of a document resource with content in markdown format is the rich rendering of the markdown - both to terminal and file (rich handles difference)
  • human readable description of a document resource with content in html format is the "print" of the html content

Changes addressed

[michael-johnston]

@AlessandroPomponio latest version is ready

Changes addressed

[AlessandroPomponio]

LGTM thanks