kernelci / kernelci/kernelci-core
(auto)generate up-to-date documentation
- 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