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.

Sign up for GitHub

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

Jump to bottom

Extend Octopoes documentation with object definitions #2946

Open
zcrt opened this issue May 14, 2024 · 2 comments · May be fixed by #4038
Open

Extend Octopoes documentation with object definitions #2946

zcrt opened this issue May 14, 2024 · 2 comments · May be fixed by #4038
Assignees
@underdarknl @stephanie0x00 @noamblitz
Labels
documentation Improvements or additions to documentation octopoes Issues related to octopoes

Comments

@zcrt
Copy link
Contributor

zcrt commented May 14, 2024

Is your feature request related to a problem? Please describe.
#2858 greatly enhanced the documentation on Octopoes objects. However, it would be even greater if explanations/definitions for (some) objects could also be added. E.g. what does it mean to be a RiskLevelSeverity Octopoes model finding? How would a DNSSPFMechanismNetBlock be defined?

Describe the solution you'd like
Ideally, docstrings will be added to the objects giving a definition in one or two sentences and maybe an example when to use this object. These docstrings could then automatically appear as a description in the documentation.

Additional context
Potential duplicate though unclear due to missing description: #2273
Related: #2622
@underdarknl underdarknl added documentation Improvements or additions to documentation octopoes Issues related to octopoes labels May 14, 2024
@ammar92
Copy link
Contributor

ammar92 commented May 22, 2024

Thanks for the suggestion. #2858 indeed served as a framework to enable model documentation. Besides the provided examples, do you have more models that need to be documented? This would help us prioritize them accordingly.

@zcrt
Copy link
Contributor Author

zcrt commented May 23, 2024

Well, ideally all of them ;). Nevertheless, the (octopoes.models.ooi.)web, reports, config, monitoring and email_security may be good starting points, while network, dns.record, dns.zone and findings may be more self-explainatory.

However, that may be my personal subjective view. (Which also means I might be able to help documenting the latter ones if you can provide some examples how you would like those documented)

@stephanie0x00 stephanie0x00 linked a pull request Jan 21, 2025 that will close this issue
Draft
9 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@underdarknl underdarknl

@stephanie0x00 stephanie0x00

@noamblitz noamblitz

Labels
documentation Improvements or additions to documentation octopoes Issues related to octopoes
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Add docstrings to Octopoes models minvws/nl-kat-coordination
5 participants
@underdarknl @ammar92 @stephanie0x00 @noamblitz @zcrt