Developers documentation

[r-c-n]

The current documentation is still fairly incomplete and high-level. It conveys the purpose of the new API and pipeline and it presents basic usage for the simplest use cases, which is a good way to start getting the attention of potential users, but at this point it still doesn't contain any relevant information for contributors: API internals, models, howtos for developers, configuration, etc.

This suggests that parts of the design are still in flux and not fully stabilized.

Any person that wants to contribute needs to read and understand the code, which also lacks proper documentation in most places. This is risky because a contributor might draw certain design conclusions from the code that may not be right or that could be provisional.

Adding a stable documentation for the API parts that are well established should be a priority to encourage external contributions.

[gctucker]

Same as for the pipeline, once we have a stable release candidate we should have no grey areas left and everything should be documented.

In the meantime, there's already the generated documentation which of course follows the state of the API itself:
https://kernelci-api.eastus.cloudapp.azure.com/latest/docs

[r-c-n]

Comment kernelci/kernelci-pipeline#329 (comment) applies here as well.

I think the generated documentation simply describes the surface of the API but, personally, I find that incomplete as a practical documentation if I don't know anything about the data models and other internal (not implementation) details. For instance, how nodes are related to each other.

[gctucker]

Right, of course it's not complete. I just wrote it's something we have in the meantime.

The API is not meant to necessarily know how the nodes relate to each other, that's something client-side services are dealing with. Like, a kernel build or kunit result etc. shouldn't be something for the API to be "aware" of, at least that's not part of the current design. And that's obviously where proper documentation will help, and we can't really document what doesn't exist yet.