diff --git a/docs/conf.py b/docs/conf.py index 50aef1d..afc2f68 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,4 +1,5 @@ import os +import re import sys from six import class_types @@ -56,15 +57,25 @@ latex_documents = [ (master_doc, 'stix2.tex', 'stix2 Documentation', 'OASIS', 'manual'), ] +def get_property_type(prop): + try: + prop_class = prop.__name__ + except AttributeError: + prop_class = prop.__class__.__name__ + prop_class = prop_class.split('Property')[0] + split_camelcase = re.sub('(?!^)([A-Z][a-z]+)', r' \1', prop_class).split() + prop_class = ' '.join(split_camelcase) + return prop_class + class STIXAttributeDocumenter(ClassDocumenter): - """Custom Sphinx extension to auto-document STIX properties. + '''Custom Sphinx extension to auto-document STIX properties. Needed because descendants of _STIXBase use `_properties` dictionaries instead of instance variables for STIX 2 objects' properties. - """ - objtype = "stixattr" - directivetype = "class" + ''' + objtype = 'stixattr' + directivetype = 'class' priority = 999 @classmethod @@ -77,10 +88,17 @@ class STIXAttributeDocumenter(ClassDocumenter): ClassDocumenter.add_content(self, more_content, no_docstring) obj = self.object - self.add_line(":Properties:", "") - for prop in obj._properties: - self.add_line(" - %s" % prop, "") - self.add_line("", "") + self.add_line(':Properties:', '') + for prop_name, prop in obj._properties.items(): + # Add metadata about the property + prop_type = get_property_type(prop) + if prop_type == 'List': + prop_type = 'List of %ss' % get_property_type(prop.contained) + if prop.required: + prop_type += ', required' + prop_str = '**%s** (*%s*)' % (prop_name, prop_type) + self.add_line(' - %s' % prop_str, '') + self.add_line('', '') def setup(app): app.add_autodocumenter(STIXAttributeDocumenter)