docs: add exaple how to build and serialize (#397)

Signed-off-by: Jan Kowalleck <[email protected]>

Author: jkowalleck

.gitattributes

@@ -1,3 +1,3 @@
 
-cyclonedx/schema/**     linguist-language
+cyclonedx/schema/**     linguist-vendored
 

docs/examples.rst

@@ -0,0 +1,23 @@
+.. # Licensed under the Apache License, Version 2.0 (the "License");
+   # you may not use this file except in compliance with the License.
+   # You may obtain a copy of the License at
+   #
+   #     http://www.apache.org/licenses/LICENSE-2.0
+   #
+   # Unless required by applicable law or agreed to in writing, software
+   # distributed under the License is distributed on an "AS IS" BASIS,
+   # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   # See the License for the specific language governing permissions and
+   # limitations under the License.
+   #
+   # SPDX-License-Identifier: Apache-2.0
+
+Examples
+========
+
+Build & Serialize
+-----------------
+
+.. literalinclude:: ../examples/build_and_serialize.py
+  :language: python
+  :linenos:

docs/index.rst

@@ -40,6 +40,7 @@ programmatically generate SBOMs.
 
    install
    architecture
+   examples
    contributing
    support
    changelog
@@ -48,4 +49,4 @@ programmatically generate SBOMs.
 .. _CycloneDX Python: https://pypi.org/project/cyclonedx-bom/
 .. _Jake: https://pypi.org/project/jake
 .. _CycloneDX Tool Center: https://cyclonedx.org/tool-center/
-.. _official examples: https://cyclonedx.org/capabilities/bomlink/#linking-external-vex-to-bom-inventory
+.. _official examples: https://cyclonedx.org/capabilities/bomlink/#linking-external-vex-to-bom-inventory

examples/build_and_serialize.py

@@ -0,0 +1,46 @@
+from cyclonedx.factory.license import LicenseFactory
+from cyclonedx.model import OrganizationalEntity, XsUri
+from cyclonedx.model.bom import Bom, LicenseChoice
+from cyclonedx.model.component import Component, ComponentType
+from cyclonedx.model.dependency import Dependency
+from cyclonedx.output.json import JsonV1Dot4
+from cyclonedx.output.xml import XmlV1Dot4
+from packageurl import PackageURL
+
+lFac = LicenseFactory()
+
+# region build the BOM
+
+bom = Bom()
+bom.metadata.component = rootComponent = Component(
+    name='myApp',
+    type=ComponentType.APPLICATION,
+    licenses=[LicenseChoice(license=lFac.make_from_string('MIT'))],
+    bom_ref='myApp',
+)
+
+component = Component(
+    type=ComponentType.LIBRARY,
+    name='some-component',
+    group='acme',
+    version='1.33.7-beta.1',
+    licenses=[LicenseChoice(license=lFac.make_from_string('(c) 2021 Acme inc.'))],
+    supplier=OrganizationalEntity(
+        name='Acme Inc',
+        urls=[XsUri('https://www.acme.org')]
+    ),
+    bom_ref='[email protected]',
+    purl=PackageURL('generic', 'acme', 'some-component', '1.33.7-beta.1')
+)
+
+bom.components.add(component)
+bom.dependencies.add(Dependency(rootComponent.bom_ref, [Dependency(component.bom_ref)]))
+
+# endregion build the BOM
+
+
+serializedJSON = JsonV1Dot4(bom).output_as_string()
+print(serializedJSON)
+
+serializedXML = XmlV1Dot4(bom).output_as_string()
+print(serializedXML)