Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

(auto)generate up-to-date documentation #2398

Open
a-wai opened this issue Feb 19, 2024 · 1 comment
Open

(auto)generate up-to-date documentation #2398

a-wai opened this issue Feb 19, 2024 · 1 comment
Labels
documentation Improvements or additions to documentation techdebt

Comments

@a-wai
Copy link
Contributor

a-wai commented Feb 19, 2024

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
Copy link
Contributor Author

a-wai commented Feb 19, 2024

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

@JenySadadia JenySadadia added the documentation Improvements or additions to documentation label Apr 27, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation techdebt
Projects
Status: No status
Development

No branches or pull requests

3 participants