kernelci / kernelci/kernelci-core

(auto)generate up-to-date documentation

Open
#2,398 1 comment 0 reactions 0 assignees View on GitHub
documentation techdebt
Dominant language
Python
Stars
120
Forks
107
Avg merge
1d 2h
Merged PRs (30d)
21

Description

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](https://staging.kernelci.org:9000/docs), 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()](https://docs.pydantic.dev/1.10/usage/schema/) creation facilities, see the following PoC for an example:
```python
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()}")
```

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reviewing the existing FastAPI documentation at the linked staging /docs endpoint and the kernelci.api.models module shown in the proof of concept. Compare how kci commands, API endpoints, and Node subclasses are currently represented, then define which generated documentation must cover all three areas. Done means the agreed documentation is generated and usable for both users and developers.

Written by the indexing model from the issue text.

Assessment

Tech stack
fastapi, python
Domain
api, backend, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.