search

Substra / substra-documentation

Documentation of the Substra software
https://docs.substra.org/
Apache License 2.0
21 stars 10 forks source link

feat: add machine-readable compatibility table #258

Closed oleobal closed 1 year ago

oleobal commented 1 year ago

This replaces the hand-written compatibility table with a YAML file that is read to generate the table, and also served by itself.

Because the "source of truth" is now machine-readable, it becomes trivial to determine the latest version:

curl docs.substra.org/releases.json | jq '.releases[0]'

Motivation

Substra has component versions, and overarching "bundle" versions that describe a set of components. This allows any script to know what "bundle version" correspond to what set of component. This by itself is mostly useless, however it is an interesting brick for other features.

It is a mandatory step to automate upgrade tests (we can't have a machine try to upgrade 0.23.1 to 0.24.0 if we can't tell it what those are).

It could also be used the other way around: by looking up whether the component versions match a given Substra release, the front could display the bundle version without us needing to write it somewhere in the deployment. One of our partners was confused by that screen and how it related to the bundle version.

Review notes

I'm unsure about file structure and also the structure of the document, please do give feedback.

I used sphinxcontrib.datatemplates because people on StackOverflow said to, but that might not be the optimal solution. I implemented it as a custom directive which was an interesting experience I do not wish to reproduce.

I wrote the "truth file" as YAML because it's easier to read and write as a human, but serving it as JSON is more convenient for users, so there is a translation step.

Here is my regex for translating the table into YAML ^^: - `(\S+) <(\S+Substra/([\w-]+)/\S+)>`__($| ?\|? `helm (\S+) <(\S+)>.*`__$) -> $3:\n version: $1\n link: $2\n helm:\n version: $5\n link: $6

oleobal commented 1 year ago

@ThibaultFy

Did you find other solutions that might lead to the same outcome ?

Implement a custom directive, basically.

ThibaultFy commented 1 year ago

What is your opinion on this ? And @guilhem-barthes, as you approve the PR I guess you think it is ok to add this contrib to the dependencies ?

oleobal commented 1 year ago

Not a fan of the Jinja solution myself, it's pretty fragile and hard to debug. And adding dependencies is always a con.

I'd say let's go for a custom extension, that being said tables are quite under-documented and that will slow down development (and this isn't the most urgent thing, I just worked on it in the off hours).