search

CycloneDX / cyclonedx-python-lib

Python implementation of OWASP CycloneDX
https://cyclonedx.org/
Apache License 2.0
68 stars 38 forks source link

[DOCS] showcases, examples & general docs improvements #396

Open jkowalleck opened 1 year ago

jkowalleck commented 1 year ago

:mega: THIS IS A CALL FOR DOCS Feel free to add pull requests with examples here:

There are currently no (complex) examples how to use this lib.

Yes, there are API docs, and small snippets, but no examples. Even the unit tests do now showcase example usage, as they are much declarative or not expressive enough.

GOAL:

jkowalleck commented 1 year ago

i would add a complex example that creates a bom B with a complete metadata.component C0 and at least one complete component C1 and have C1 as a dependency of C0 so a dependency tree is rendered. For the licenses, I would showcase the shipped factory. Then have this B serialized once to JSON and once to XML to CDX1.4 (And if validation is a public available feature of the lib, then validate the JSON/XML against the appropriate schema.)

similar to this here:

jkowalleck commented 1 year ago

@ptdropper do you have additional ideas for specific examples? something you were looking for in the past or something you might need in the future?

jkowalleck commented 1 year ago

examples are rendered here, too https://cyclonedx-python-library.readthedocs.io/en/latest/examples.html

schlenk commented 1 year ago

@jkowalleck Is the dependency logic with add() idiomatic?

https://github.com/CycloneDX/cyclonedx-python-lib/blob/4a72f515ad7b5e46a07f31bea18a94b162e87715/examples/build_and_serialize.py#L37

wouldn't this be more idiomatic?

bom.register_dependency(rootComponent, [component])
jkowalleck commented 1 year ago

re https://github.com/CycloneDX/cyclonedx-python-lib/issues/396#issuecomment-1612133613 @schlenk I like your proposal. Would you prepare a pullrequest to have the examples modified? added via #403