(auto)generate up-to-date documentation

[a-wai]

As mentioned in other issues (such as #2040 and #2092), the new system lacks documentation for both users and developers.

A first step in solving this problem could be to look at auto-generation for items easily documented in the code itself. this includes:

• kci commands
• API endpoints
  • fastapi already provides some kind of endpoint/schema documentation, but it's incomplete and barely usable; we could, however, have a look at how this works and get some inspiration there
• Node types & formats
  • Partly provided by fastapi (see above) but only documents the top-level Node model, not any of its sub-classes
  • We could create a script which would leverage pydantic's schema() creation facilities, see the following PoC for an example:

import kernelci, inspect
from kernelci.api.models import *

def iskcimodel(model):
    if (inspect.isclass(model) and
        model.__module__ == "kernelci.api.models" and
        hasattr(model, 'schema')):
        return True
    return False

for name, myclass in inspect.getmembers(kernelci.api.models, iskcimodel):
    print(f"{name} -> {myclass.schema()}")

[a-wai]

Some additional notes: sphinx could be an interesting option for generating documentation (we could then post-process if needed), as it is extensible; of particular interest to us, the following modules are available:

• sphinx-click can be used to document Click-based applications like our kci tool
• sphinx-pydantic provides similar functionality for data models using pydantic