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

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

Open
5 tasks done
jkowalleck opened this issue Jun 28, 2023 · 5 comments
Open
5 tasks done

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

jkowalleck opened this issue Jun 28, 2023 · 5 comments
Labels
documentation Improvements or additions to documentation help wanted Extra attention is needed

Comments

@jkowalleck
Copy link
Member

jkowalleck commented Jun 28, 2023

📣 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:

  • have examples in a examples folder
  • link the examples in the README
  • link the examples in the (api)-docs
  • prevent examples dir from being shipped (sdist/bdist)
  • have examples run in CI

@jkowalleck jkowalleck added the documentation Improvements or additions to documentation label Jun 28, 2023
@jkowalleck
Copy link
Member Author

jkowalleck commented Jun 28, 2023

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

@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
Copy link
Member Author

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

@schlenk
Copy link
Contributor

schlenk commented Jun 28, 2023

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

bom.dependencies.add(Dependency(rootComponent.bom_ref, [Dependency(component.bom_ref)]))

wouldn't this be more idiomatic?

bom.register_dependency(rootComponent, [component])

@jkowalleck
Copy link
Member Author

jkowalleck commented Jun 28, 2023

re #396 (comment)
@schlenk I like your proposal. Would you prepare a pullrequest to have the examples modified?
added via #403

@jkowalleck jkowalleck pinned this issue Jun 28, 2023
@jkowalleck jkowalleck changed the title showcases and examples DOCS: showcases and examples Jun 28, 2023
@jkowalleck jkowalleck added the help wanted Extra attention is needed label Jun 28, 2023
@jkowalleck jkowalleck changed the title DOCS: showcases and examples DOCS: showcases, examples & general docs improvements Jun 30, 2023
@jkowalleck jkowalleck unpinned this issue Sep 18, 2023
@jkowalleck jkowalleck changed the title DOCS: showcases, examples & general docs improvements [DOCS] showcases, examples & general docs improvements Nov 16, 2023
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 help wanted Extra attention is needed
Projects
None yet
Development

No branches or pull requests

2 participants