[DOCS] showcases, examples & general docs improvements

[jkowalleck]

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

• https://github.com/CycloneDX/cyclonedx-python-lib/tree/main/examples
• https://github.com/CycloneDX/cyclonedx-python-lib/blob/main/docs/examples.rst

---

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]

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:

• https://github.com/CycloneDX/cyclonedx-javascript-library/blob/main/examples/node-typescript/example.mjs/src/example.ts
• https://github.com/CycloneDX/cyclonedx-php-library/blob/master/examples/build_and_serialize.php

[jkowalleck]

@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]

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

[schlenk]

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

cyclonedx-python-lib/examples/build_and_serialize.py

Line 37 in 4a72f51

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

wouldn't this be more idiomatic?

bom.register_dependency(rootComponent, [component])

[jkowalleck]

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