Merge pull request #465 from oasis-open/equivalence-documentation

Equivalence module documentation fix

.gitignore

@@ -55,7 +55,8 @@ coverage.xml
 # Sphinx documentation
 docs/_build/
 .ipynb_checkpoints
-default_sem_eq_weights.rst
+graph_default_sem_eq_weights.rst
+object_default_sem_eq_weights.rst
 
 # PyBuilder
 target/

docs/api/equivalence/pattern/compare/stix2.equivalence.pattern.compare.comparison.rst

@@ -1,5 +1,5 @@
 comparison
-==============
+============================================
 
 .. automodule:: stix2.equivalence.pattern.compare.comparison
-   :members:
+   :members:

docs/api/equivalence/pattern/compare/stix2.equivalence.pattern.compare.observation.rst

@@ -1,5 +1,5 @@
 observation
-==============
+=============================================
 
 .. automodule:: stix2.equivalence.pattern.compare.observation
-   :members:
+   :members:

docs/api/equivalence/pattern/stix2.equivalence.pattern.compare.rst

@@ -0,0 +1,5 @@
+compare
+=================================
+
+.. automodule:: stix2.equivalence.pattern.compare
+   :members:

docs/api/equivalence/pattern/stix2.equivalence.pattern.transform.rst

@@ -0,0 +1,5 @@
+transform
+===================================
+
+.. automodule:: stix2.equivalence.pattern.transform
+   :members:

docs/api/equivalence/pattern/transform/stix2.equivalence.pattern.transform.comparison.rst

@@ -1,5 +1,5 @@
 comparison
-==============
+==============================================
 
 .. automodule:: stix2.equivalence.pattern.transform.comparison
-   :members:
+   :members:

docs/api/equivalence/pattern/transform/stix2.equivalence.pattern.transform.observation.rst

@@ -1,5 +1,5 @@
 observation
-==============
+===============================================
 
 .. automodule:: stix2.equivalence.pattern.transform.observation
-   :members:
+   :members:

docs/api/equivalence/pattern/transform/stix2.equivalence.pattern.transform.specials.rst

@@ -1,5 +1,5 @@
 specials
-==============
+============================================
 
 .. automodule:: stix2.equivalence.pattern.transform.specials
-   :members:
+   :members:

docs/api/equivalence/stix2.equivalence.graph.rst

@@ -1,5 +1,5 @@
 graph
-=====
+=======================
 
 .. automodule:: stix2.equivalence.graph
-   :members:
+   :members:

docs/api/equivalence/stix2.equivalence.object.rst

@@ -1,5 +1,5 @@
 object
-======
+========================
 
 .. automodule:: stix2.equivalence.object
-   :members:
+   :members:

docs/conf.py

@@ -8,7 +8,8 @@ from six import class_types
 from sphinx.ext.autodoc import ClassDocumenter
 
 from stix2.base import _STIXBase
-from stix2.environment import WEIGHTS
+from stix2.equivalence.graph import GRAPH_WEIGHTS
+from stix2.equivalence.object import WEIGHTS
 from stix2.version import __version__
 
 sys.path.insert(0, os.path.abspath('..'))
@@ -62,12 +63,19 @@ latex_documents = [
 ]
 
 # Add a formatted version of environment.WEIGHTS
-default_sem_eq_weights = json.dumps(WEIGHTS, indent=4, default=lambda o: o.__name__)
+object_default_sem_eq_weights = json.dumps(WEIGHTS, indent=4, default=lambda o: o.__name__)
-default_sem_eq_weights = default_sem_eq_weights.replace('\n', '\n    ')
+object_default_sem_eq_weights = object_default_sem_eq_weights.replace('\n', '\n    ')
-default_sem_eq_weights = default_sem_eq_weights.replace('               "', '               ')
+object_default_sem_eq_weights = object_default_sem_eq_weights.replace('               "', '               ')
-default_sem_eq_weights = default_sem_eq_weights.replace('"\n', '\n')
+object_default_sem_eq_weights = object_default_sem_eq_weights.replace('"\n', '\n')
-with open('default_sem_eq_weights.rst', 'w') as f:
+with open('object_default_sem_eq_weights.rst', 'w') as f:
-    f.write(".. code-block:: py\n\n   {}\n\n".format(default_sem_eq_weights))
+    f.write(".. code-block:: python\n\n   {}\n\n".format(object_default_sem_eq_weights))
+
+graph_default_sem_eq_weights = json.dumps(GRAPH_WEIGHTS, indent=4, default=lambda o: o.__name__)
+graph_default_sem_eq_weights = graph_default_sem_eq_weights.replace('\n', '\n    ')
+graph_default_sem_eq_weights = graph_default_sem_eq_weights.replace('               "', '               ')
+graph_default_sem_eq_weights = graph_default_sem_eq_weights.replace('"\n', '\n')
+with open('graph_default_sem_eq_weights.rst', 'w') as f:
+    f.write(".. code-block:: python\n\n   {}\n\n".format(graph_default_sem_eq_weights))
 
 
 def get_property_type(prop):

docs/guide/equivalence.ipynb

@@ -2165,15 +2165,17 @@
     "The weights dictionary should contain both the weight and the comparison function for each property. You may use the default weights and functions, or provide your own.\n",
     "\n",
     "##### Existing comparison functions\n",
-    "For reference, here is a list of the comparison functions already built in the codebase (found in [stix2/environment.py](../api/stix2.environment.rst#stix2.environment.Environment)):\n",
+    "For reference, here is a list of the comparison functions already built in the codebase (found in [stix2/equivalence/object](../api/equivalence/stix2.equivalence.object.rst#module-stix2.equivalence.object)):\n",
     "\n",
-    " - [custom_pattern_based](../api/stix2.environment.rst#stix2.environment.custom_pattern_based)\n",
+    " - [custom_pattern_based](../api/equivalence/stix2.equivalence.object.rst#stix2.equivalence.object.custom_pattern_based)\n",
-    " - [exact_match](../api/stix2.environment.rst#stix2.environment.exact_match)\n",
+    " - [exact_match](../api/equivalence/stix2.equivalence.object.rst#stix2.equivalence.object.exact_match)\n",
-    " - [partial_external_reference_based](../api/stix2.environment.rst#stix2.environment.partial_external_reference_based)\n",
+    " - [list_reference_check](../api/equivalence/stix2.equivalence.object.rst#stix2.equivalence.object.list_reference_check)\n",
-    " - [partial_list_based](../api/stix2.environment.rst#stix2.environment.partial_list_based)\n",
+    " - [partial_external_reference_based](../api/equivalence/stix2.equivalence.object.rst#stix2.equivalence.object.partial_external_reference_based)\n",
-    " - [partial_location_distance](../api/stix2.environment.rst#stix2.environment.partial_location_distance)\n",
+    " - [partial_list_based](../api/equivalence/stix2.equivalence.object.rst#stix2.equivalence.object.partial_list_based)\n",
-    " - [partial_string_based](../api/stix2.environment.rst#stix2.environment.partial_string_based)\n",
+    " - [partial_location_distance](../api/equivalence/stix2.equivalence.object.rst#stix2.equivalence.object.partial_location_distance)\n",
-    " - [partial_timestamp_based](../api/stix2.environment.rst#stix2.environment.partial_timestamp_based)\n",
+    " - [partial_string_based](../api/equivalence/stix2.equivalence.object.rst#stix2.equivalence.object.partial_string_based)\n",
+    " - [partial_timestamp_based](../api/equivalence/stix2.equivalence.object.rst#stix2.equivalence.object.partial_timestamp_based)\n",
+    " - [reference_check](../api/equivalence/stix2.equivalence.object.rst#stix2.equivalence.object.reference_check)\n",
     "\n",
     "For instance, if we wanted to compare two of the `ThreatActor`s from before, but use our own weights, then we could do the following:"
    ]

requirements.txt

@@ -1,5 +1,6 @@
 bumpversion
 ipython
+nbconvert<6
 nbsphinx==0.4.3
 pre-commit
 pygments<3,>=2.4.1

stix2/environment.py

@@ -4,7 +4,7 @@ import copy
 from .datastore import CompositeDataSource, DataStoreMixin
 from .equivalence.graph import graphically_equivalent
 from .equivalence.object import (  # noqa: F401
-    check_property_present, custom_pattern_based, exact_match,
+    WEIGHTS, check_property_present, custom_pattern_based, exact_match,
     list_reference_check, partial_external_reference_based, partial_list_based,
     partial_location_distance, partial_string_based, partial_timestamp_based,
     reference_check, semantically_equivalent,
@@ -220,9 +220,9 @@ class Environment(DataStoreMixin):
             or methods can be fine tuned for a particular use case.
 
         Note:
-            Default weights_dict:
+            Default weight_dict:
 
-            .. include:: ../default_sem_eq_weights.rst
+            .. include:: ../object_default_sem_eq_weights.rst
 
         Note:
             This implementation follows the Semantic Equivalence Committee Note.
@@ -258,9 +258,9 @@ class Environment(DataStoreMixin):
             or methods can be fine tuned for a particular use case.
 
         Note:
-            Default weights_dict:
+            Default weight_dict:
 
-            .. include:: ../default_sem_eq_weights.rst
+            .. include:: ../graph_default_sem_eq_weights.rst
 
         Note:
             This implementation follows the Semantic Equivalence Committee Note.

stix2/equivalence/graph/__init__.py

@@ -1,3 +1,4 @@
+"""Python APIs for STIX 2 Graph-based Semantic Equivalence."""
 import logging
 
 from ..object import (
@@ -36,7 +37,7 @@ def graphically_equivalent(ds1, ds2, prop_scores={}, **weight_dict):
     Note:
         Default weights_dict:
 
-        .. include:: ../default_sem_eq_weights.rst
+        .. include:: ../../graph_default_sem_eq_weights.rst
 
     Note:
         This implementation follows the Semantic Equivalence Committee Note.
@@ -133,4 +134,4 @@ GRAPH_WEIGHTS.update({
         "ds2": None,
         "max_depth": 1,
     },
-})  #: :autodoc-skip:
+})  # :autodoc-skip:

stix2/equivalence/object/__init__.py

@@ -1,3 +1,4 @@
+"""Python APIs for STIX 2 Object-based Semantic Equivalence."""
 import logging
 import time
 
@@ -32,7 +33,7 @@ def semantically_equivalent(obj1, obj2, prop_scores={}, **weight_dict):
     Note:
         Default weights_dict:
 
-        .. include:: ../default_sem_eq_weights.rst
+        .. include:: ../../object_default_sem_eq_weights.rst
 
     Note:
         This implementation follows the Semantic Equivalence Committee Note.
@@ -448,4 +449,4 @@ WEIGHTS = {
     "_internal": {
         "ignore_spec_version": False,
     },
-}  #: :autodoc-skip:
+}  # :autodoc-skip:

stix2/equivalence/pattern/__init__.py

@@ -1,7 +1,7 @@
 """Python APIs for STIX 2 Pattern Semantic Equivalence.
 
 .. autosummary::
-   :toctree: patterns
+   :toctree: pattern
 
    compare
    transform