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

Equivalence module documentation fix
2020-10-18 22:03:35 -04:00 · 2020-10-18 22:03:35 -04:00 · cfb518a84b
parent fb705c4885 e08a26a39c
commit cfb518a84b
17 changed files with 64 additions and 40 deletions
--- a/.gitignore
+++ b/.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/
--- a/docs/api/equivalence/pattern/compare/stix2.equivalence.pattern.compare.comparison.rst
+++ b/docs/api/equivalence/pattern/compare/stix2.equivalence.pattern.compare.comparison.rst
@ -1,5 +1,5 @@
 comparison
-==============
+============================================

 .. automodule:: stix2.equivalence.pattern.compare.comparison
-   :members:
+   :members:
--- a/docs/api/equivalence/pattern/compare/stix2.equivalence.pattern.compare.observation.rst
+++ b/docs/api/equivalence/pattern/compare/stix2.equivalence.pattern.compare.observation.rst
@ -1,5 +1,5 @@
 observation
-==============
+=============================================

 .. automodule:: stix2.equivalence.pattern.compare.observation
-   :members:
+   :members:
--- a/docs/api/equivalence/pattern/stix2.equivalence.pattern.compare.rst
+++ b/docs/api/equivalence/pattern/stix2.equivalence.pattern.compare.rst
@ -0,0 +1,5 @@
+compare
+=================================
+
+.. automodule:: stix2.equivalence.pattern.compare
+   :members:
--- a/docs/api/equivalence/pattern/stix2.equivalence.pattern.transform.rst
+++ b/docs/api/equivalence/pattern/stix2.equivalence.pattern.transform.rst
@ -0,0 +1,5 @@
+transform
+===================================
+
+.. automodule:: stix2.equivalence.pattern.transform
+   :members:
--- a/docs/api/equivalence/pattern/transform/stix2.equivalence.pattern.transform.comparison.rst
+++ b/docs/api/equivalence/pattern/transform/stix2.equivalence.pattern.transform.comparison.rst
@ -1,5 +1,5 @@
 comparison
-==============
+==============================================

 .. automodule:: stix2.equivalence.pattern.transform.comparison
-   :members:
+   :members:
--- a/docs/api/equivalence/pattern/transform/stix2.equivalence.pattern.transform.observation.rst
+++ b/docs/api/equivalence/pattern/transform/stix2.equivalence.pattern.transform.observation.rst
@ -1,5 +1,5 @@
 observation
-==============
+===============================================

 .. automodule:: stix2.equivalence.pattern.transform.observation
-   :members:
+   :members:
--- a/docs/api/equivalence/pattern/transform/stix2.equivalence.pattern.transform.specials.rst
+++ b/docs/api/equivalence/pattern/transform/stix2.equivalence.pattern.transform.specials.rst
@ -1,5 +1,5 @@
 specials
-==============
+============================================

 .. automodule:: stix2.equivalence.pattern.transform.specials
-   :members:
+   :members:
--- a/docs/api/equivalence/graph/stix2.equivalence.graph.rst
+++ b/docs/api/equivalence/graph/stix2.equivalence.graph.rst
@ -1,5 +1,5 @@
 graph
-=====
+=======================

 .. automodule:: stix2.equivalence.graph
-   :members:
+   :members:
--- a/docs/api/equivalence/object/stix2.equivalence.object.rst
+++ b/docs/api/equivalence/object/stix2.equivalence.object.rst
@ -1,5 +1,5 @@
 object
-======
+========================

 .. automodule:: stix2.equivalence.object
-   :members:
+   :members:
--- a/docs/conf.py
+++ b/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__)
-default_sem_eq_weights = default_sem_eq_weights.replace('\n', '\n    ')
-default_sem_eq_weights = default_sem_eq_weights.replace('               "', '               ')
-default_sem_eq_weights = default_sem_eq_weights.replace('"\n', '\n')
-with open('default_sem_eq_weights.rst', 'w') as f:
-    f.write(".. code-block:: py\n\n   {}\n\n".format(default_sem_eq_weights))
+object_default_sem_eq_weights = json.dumps(WEIGHTS, indent=4, default=lambda o: o.__name__)
+object_default_sem_eq_weights = object_default_sem_eq_weights.replace('\n', '\n    ')
+object_default_sem_eq_weights = object_default_sem_eq_weights.replace('               "', '               ')
+object_default_sem_eq_weights = object_default_sem_eq_weights.replace('"\n', '\n')
+with open('object_default_sem_eq_weights.rst', 'w') as f:
+    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):
--- a/docs/guide/equivalence.ipynb
+++ b/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",
-    " - [exact_match](../api/stix2.environment.rst#stix2.environment.exact_match)\n",
-    " - [partial_external_reference_based](../api/stix2.environment.rst#stix2.environment.partial_external_reference_based)\n",
-    " - [partial_list_based](../api/stix2.environment.rst#stix2.environment.partial_list_based)\n",
-    " - [partial_location_distance](../api/stix2.environment.rst#stix2.environment.partial_location_distance)\n",
-    " - [partial_string_based](../api/stix2.environment.rst#stix2.environment.partial_string_based)\n",
-    " - [partial_timestamp_based](../api/stix2.environment.rst#stix2.environment.partial_timestamp_based)\n",
+    " - [custom_pattern_based](../api/equivalence/stix2.equivalence.object.rst#stix2.equivalence.object.custom_pattern_based)\n",
+    " - [exact_match](../api/equivalence/stix2.equivalence.object.rst#stix2.equivalence.object.exact_match)\n",
+    " - [list_reference_check](../api/equivalence/stix2.equivalence.object.rst#stix2.equivalence.object.list_reference_check)\n",
+    " - [partial_external_reference_based](../api/equivalence/stix2.equivalence.object.rst#stix2.equivalence.object.partial_external_reference_based)\n",
+    " - [partial_list_based](../api/equivalence/stix2.equivalence.object.rst#stix2.equivalence.object.partial_list_based)\n",
+    " - [partial_location_distance](../api/equivalence/stix2.equivalence.object.rst#stix2.equivalence.object.partial_location_distance)\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:"
   ]
--- a/requirements.txt
+++ b/requirements.txt
@ -1,5 +1,6 @@
 bumpversion
 ipython
+nbconvert<6
 nbsphinx==0.4.3
 pre-commit
 pygments<3,>=2.4.1
--- a/stix2/environment.py
+++ b/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.
--- a/stix2/equivalence/graph/init.py
+++ b/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:
--- a/stix2/equivalence/object/init.py
+++ b/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:
--- a/stix2/equivalence/pattern/init.py
+++ b/stix2/equivalence/pattern/init.py
@ -1,7 +1,7 @@
 """Python APIs for STIX 2 Pattern Semantic Equivalence.

 .. autosummary::
-   :toctree: patterns
+   :toctree: pattern

   compare
   transform