Add RTD generated docs

.readthedocs.yml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.8"
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+python:
+   install:
+      - method: pip
+        path: .
+        extra_requirements: [doc]

Makefile

@@ -10,6 +10,7 @@ CODESPELL=$(VENV)/bin/codespell
 PIP=$(VENV)/bin/pip
 BLACK=$(VENV)/bin/black
 STUBGEN=$(VENV)/bin/stubgen
+SPHINX_BUILD=$(VENV)/bin/sphinx-build
 
 setup: requirements.txt
 	virtualenv ./env
@@ -20,6 +21,7 @@ setup: requirements.txt
 clean:
 	rm -rf ./build
 	rm -rf ./htmlcov
+	rm -rf ./docs/build
 
 $(PYTEST):
 	$(PIP) install pytest-cov pylint
@@ -33,6 +35,9 @@ $(STUBGEN):
 $(BLACK):
 	$(PIP) install black
 
+$(SPHINX_BUILD):
+	$(PIP) install sphinx sphinx_autodoc_typehints sphinx_rtd_theme
+
 check: $(PYTEST) $(MYPY)
 	$(MYPY) --check-untyped-defs uswid
 	$(PYTEST) uswid
@@ -49,6 +54,9 @@ codespell: $(CODESPELL)
 	*.pyc,\
 	env
 
+docs: $(SPHINX_BUILD) docs/index.rst
+	PYTHONPATH=. $(SPHINX_BUILD) docs/ docs/build/html
+
 pkg: $(STUBGEN)
 	$(STUBGEN) --output . --package uswid
 	$(PYTHON) setup.py sdist bdist_wheel

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python
+# from importlib.metadata import version as get_version
+# from packaging.version import parse
+
+import subprocess
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx_autodoc_typehints",
+]
+
+templates_path = ["_templates"]
+source_suffix = ".rst"
+master_doc = "index"
+project = "uswid"
+author = "Richard Hughes"
+copyright = "2021, " + author
+
+# v = parse(get_version(project))
+# version = v.base_version
+# release = v.public
+
+try:
+    release = subprocess.check_output(
+        ["git", "describe"], stderr=subprocess.DEVNULL
+    ).decode("utf-8")
+except (subprocess.CalledProcessError, PermissionError, FileNotFoundError):
+    release = ""
+
+language = "en"
+
+exclude_patterns = ["_build"]
+pygments_style = "sphinx"
+highlight_language = "default"
+todo_include_todos = False
+autodoc_default_options = {
+    "special-members": "__init__",
+}
+
+html_theme = "sphinx_rtd_theme"
+htmlhelp_basename = project.replace("-", "") + "doc"
+
+intersphinx_mapping = {"python": ("https://docs.python.org/", None)}

docs/index.rst

@@ -0,0 +1,22 @@
+uSWID allows you to **create**, **convert** and **merge** SBoM metadata to and from most SBoM formats,
+with the initial focus being functionality useful for firmware files.
+
+Table of contents
+-----------------
+
+.. toctree::
+   :maxdepth: 2
+
+   usage
+   versionhistory
+   Container <modules/container>
+   Entity <modules/entity>
+   Enums <modules/enums>
+   Errors <modules/errors>
+   Format <modules/format>
+   Identity <modules/identity>
+   Link <modules/link>
+   Payload <modules/payload>
+   Hash <modules/hash>
+
+* :ref:`API reference <modindex>`

docs/modules/container.rst

@@ -0,0 +1,6 @@
+:mod:`uswid.container`
+======================
+
+.. automodule:: uswid.container
+    :members:
+    :undoc-members:

docs/modules/entity.rst

@@ -0,0 +1,6 @@
+:mod:`uswid.entity`
+===================
+
+.. automodule:: uswid.entity
+    :members:
+    :undoc-members:

docs/modules/enums.rst

@@ -0,0 +1,6 @@
+:mod:`uswid.enums`
+==================
+
+.. automodule:: uswid.enums
+    :members:
+    :undoc-members:

docs/modules/errors.rst

@@ -0,0 +1,6 @@
+:mod:`uswid.errors`
+===================
+
+.. automodule:: uswid.errors
+    :members:
+    :undoc-members:

docs/modules/format.rst

@@ -0,0 +1,6 @@
+:mod:`uswid.format`
+===================
+
+.. automodule:: uswid.format
+    :members:
+    :undoc-members:

docs/modules/hash.rst

@@ -0,0 +1,6 @@
+:mod:`uswid.hash`
+=================
+
+.. automodule:: uswid.hash
+    :members:
+    :undoc-members:

docs/modules/identity.rst

@@ -0,0 +1,6 @@
+:mod:`uswid.identity`
+=====================
+
+.. automodule:: uswid.identity
+    :members:
+    :undoc-members:

docs/modules/link.rst

@@ -0,0 +1,6 @@
+:mod:`uswid.link`
+=================
+
+.. automodule:: uswid.link
+    :members:
+    :undoc-members:

docs/modules/payload.rst

@@ -0,0 +1,6 @@
+:mod:`uswid.payload`
+====================
+
+.. automodule:: uswid.payload
+    :members:
+    :undoc-members:

docs/usage.rst

@@ -0,0 +1,7 @@
+Basic usage
+===========
+
+Serializing and deserializing with uswid is pretty straightforward::
+
+    from uswid import dumps, loads, load
+

docs/versionhistory.rst

@@ -0,0 +1,18 @@
+Version history
+===============
+
+.. currentmodule:: uswid
+
+This library adheres to `Semantic Versioning <http://semver.org/>`_.
+
+**UNRELEASED**
+
+- Added support for Python 3.12
+
+**0.3.0** (2022-12-07)
+
+- Fo bar baz
+
+**0.2.0** (2016-06-08)
+
+- Initial release

pylintrc

@@ -8,7 +8,7 @@ extension-pkg-whitelist=lxml
 [MESSAGES CONTROL]
 
 # Disable the message, report, category or checker with the given id(s)
-disable=invalid-name,len-as-condition,missing-docstring,too-many-return-statements,too-many-branches,import-outside-toplevel,too-many-public-methods,abstract-method,unsubscriptable-object,too-many-instance-attributes,consider-using-enumerate,cyclic-import,consider-using-f-string
+disable=invalid-name,len-as-condition,too-many-return-statements,too-many-branches,import-outside-toplevel,too-many-public-methods,abstract-method,unsubscriptable-object,too-many-instance-attributes,consider-using-enumerate,cyclic-import,consider-using-f-string,missing-module-docstring
 
 [REPORTS]
 

uswid/cli.py

@@ -46,7 +46,7 @@
 from uswid.format_cyclonedx import uSwidFormatCycloneDX
 
 
-def adjust_SectionSize(sz, align):
+def _adjust_SectionSize(sz, align):
     if sz % align:
         sz = ((sz + align) // align) * align
     return sz
@@ -161,6 +161,8 @@ def _save_efi_objcopy(
 
 
 class SwidFormat(IntEnum):
+    """Detected file format"""
+
     UNKNOWN = 0
     INI = 1
     XML = 2
@@ -214,6 +216,7 @@ def _type_for_fmt(
 
 
 def main():
+    """Main entrypoint"""
     parser = argparse.ArgumentParser(
         prog="uswid", description="Generate CoSWID metadata"
     )

uswid/container.py

@@ -14,7 +14,7 @@
 
 
 class uSwidContainer:
-    """represents a uSWID container"""
+    """Represents a uSWID container"""
 
     def __init__(self, identities: Optional[List[uSwidIdentity]] = None) -> None:
         self._identities: List[uSwidIdentity] = []
@@ -27,10 +27,11 @@ def __iter__(self) -> Generator:
             yield identity
 
     def append(self, identity: uSwidIdentity) -> None:
+        """Add an identity to the container"""
         self._identities.append(identity)
 
     def merge(self, identity: uSwidIdentity) -> Optional[uSwidIdentity]:
-        """merges one identity into another, returning False if the tag_id does not exist"""
+        """Merges one identity into another, returning None if the tag_id does not exist"""
 
         # just patching the default (and only) identity
         if not identity.tag_id:
@@ -53,7 +54,7 @@ def merge(self, identity: uSwidIdentity) -> Optional[uSwidIdentity]:
         return None
 
     def get_default(self) -> Optional[uSwidIdentity]:
-        """returns the existing identity, or creates one if none already exist"""
+        """Returns the existing identity, or creates one if none already exist"""
 
         if len(self._identities) > 1:
             return None
@@ -62,7 +63,7 @@ def get_default(self) -> Optional[uSwidIdentity]:
         return self._identities[0]
 
     def _get_by_id(self, tag_id: str) -> Optional[uSwidIdentity]:
-        """returns the identity that matches the tag ID"""
+        """Returns the identity that matches the tag ID"""
 
         for identity in self._identities:
             if identity.tag_id == tag_id:

uswid/entity.py

@@ -12,6 +12,8 @@
 
 
 class uSwidEntityRole(IntEnum):
+    """Represents an enumerated role"""
+
     TAG_CREATOR = 1
     SOFTWARE_CREATOR = 2
     AGGREGATOR = 3
@@ -21,7 +23,7 @@ class uSwidEntityRole(IntEnum):
 
 
 class uSwidEntity:
-    """represents a SWID entity"""
+    """Represents a SWID entity"""
 
     def __init__(
         self,
@@ -30,8 +32,11 @@ def __init__(
         roles: Optional[List[uSwidEntityRole]] = None,
     ):
         self.name: Optional[str] = name
+        """Name"""
         self.regid: Optional[str] = regid
+        """Registration ID, e.g. com.intel"""
         self.roles: List[uSwidEntityRole] = []
+        """Role of the entity, e.g. ``uSwidEntityRole.MAINTAINER``"""
         if roles:
             self.roles.extend(roles)
 

uswid/enums.py

@@ -9,6 +9,8 @@
 
 
 class uSwidGlobalMap(IntEnum):
+    """Represents an enumerated tag ID"""
+
     TAG_ID = 0
     SOFTWARE_NAME = 1
     ENTITY = 2
@@ -69,6 +71,8 @@ class uSwidGlobalMap(IntEnum):
 
 
 class uSwidVersionScheme(IntEnum):
+    """Represents an enumerated version scheme"""
+
     MULTIPARTNUMERIC = 1
     MULTIPARTNUMERIC_SUFFIX = 2
     ALPHANUMERIC = 3

uswid/errors.py

@@ -7,4 +7,4 @@
 
 
 class NotSupportedError(NotImplementedError):
-    pass
+    """Error for when an operation is not supported by the format"""

uswid/format.py

@@ -14,11 +14,15 @@
 
 
 class uSwidFormatBase:
+    """baseclass for formats to subclass"""
+
     def __init__(self) -> None:
         pass
 
     def load(self, blob: bytes, path: Optional[str] = None) -> "uSwidContainer":
+        """load a blob of data"""
         raise NotImplementedError
 
     def save(self, container: "uSwidContainer") -> bytes:
+        """save into a blob of data"""
         raise NotImplementedError