more docs

.gitignore

@@ -66,3 +66,6 @@ target/
 .python-version*
 
 temp*
+
+# env file
+.env

deepdiff/delta.py

@@ -35,7 +35,7 @@
 NUMPY_TO_LIST = 'NUMPY_TO_LIST'
 NOT_VALID_NUMPY_TYPE = "{} is not a valid numpy type."
 
-doc = get_doc('delta_doc.rst')
+doc = get_doc('delta.rst')
 
 
 class DeltaError(ValueError):

docs/_static/custom.css

@@ -0,0 +1,16 @@
+/* latin-ext */
+@font-face {
+  font-family: 'Open Sans';
+  font-style: normal;
+  font-weight: 400;
+  src: local('Open Sans Regular'), local('OpenSans-Regular'), url(https://fonts.gstatic.com/s/opensans/v17/mem8YaGs126MiZpBA-UFW50bbck.woff2) format('woff2');
+  unicode-range: U+0100-024F, U+0259, U+1E00-1EFF, U+2020, U+20A0-20AB, U+20AD-20CF, U+2113, U+2C60-2C7F, U+A720-A7FF;
+}
+/* latin */
+@font-face {
+  font-family: 'Open Sans';
+  font-style: normal;
+  font-weight: 400;
+  src: local('Open Sans Regular'), local('OpenSans-Regular'), url(https://fonts.gstatic.com/s/opensans/v17/mem8YaGs126MiZpBA-UFVZ0b.woff2) format('woff2');
+  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}

docs/_templates/about.html

@@ -0,0 +1,57 @@
+{% if theme_logo %}
+<p class="logo">
+  <a href="/">
+    <img class="logo" src="{{ pathto('_static/' ~ theme_logo, 1) }}" alt="Logo"/>
+    {% if theme_logo_name|lower == 'true' %}
+    <h1 class="logo logo-name">{{ project }}</h1>
+    {% endif %}
+  </a>
+</p>
+{% else %}
+<h1 class="logo"><a href="{{ pathto(master_doc) }}">{{ project }}</a></h1>
+{% endif %}
+
+{% if theme_description %}
+<p class="blurb">{{ theme_description }}</p>
+{% endif %}
+
+{% if theme_github_user and theme_github_repo %}
+{% if theme_github_button|lower == 'true' %}
+<p>
+<iframe src="https://ghbtns.com/github-btn.html?user={{ theme_github_user }}&repo={{ theme_github_repo }}&type={{ theme_github_type }}&count={{ theme_github_count }}&size=large&v=2"
+  allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
+</p>
+{% endif %}
+{% endif %}
+
+{% if theme_travis_button|lower != 'false' %}
+{% if theme_travis_button|lower == 'true' %}
+    {% set path = theme_github_user + '/' + theme_github_repo %}
+{% else %}
+    {% set path = theme_travis_button %}
+{% endif %}
+<p>
+<a class="badge" href="https://travis-ci.org/{{ path }}">
+    <img
+        alt="https://secure.travis-ci.org/{{ path }}.svg?branch={{ theme_badge_branch }}"
+        src="https://secure.travis-ci.org/{{ path }}.svg?branch={{ theme_badge_branch }}"
+    />
+</a>
+</p>
+{% endif %}
+
+{% if theme_codecov_button|lower != 'false' %}
+{% if theme_codecov_button|lower == 'true' %}
+    {% set path = theme_github_user + '/' + theme_github_repo %}
+{% else %}
+    {% set path = theme_codecov_button %}
+{% endif %}
+<p>
+<a class="badge" href="https://codecov.io/github/{{ path }}">
+    <img
+    alt="https://codecov.io/github/{{ path }}/coverage.svg?branch={{ theme_badge_branch }}"
+    src="https://codecov.io/github/{{ path }}/coverage.svg?branch={{ theme_badge_branch }}"
+    />
+</a>
+</p>
+{% endif %}

docs/_templates/navigation.html

@@ -0,0 +1,10 @@
+<h3 class="logo"><a href="{{ pathto(master_doc) }}">{{ project }} {{ version }}</a></h3>
+{{ toctree(includehidden=theme_sidebar_includehidden, collapse=theme_sidebar_collapse) }}
+{% if theme_extra_nav_links %}
+<hr />
+<ul>
+    {% for text, uri in theme_extra_nav_links.items() %}
+    <li class="toctree-l1"><a href="{{ uri }}">{{ text }}</a></li>
+    {% endfor %}
+</ul>
+{% endif %}

docs/buildme.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python
+"""
+Create a .env file in this folder that has BUILD_PATH defined, otherwise the _build will be used.
+Then run ./buildme.py
+It will remove the contents of the BUILD_PATH folder and recreate it.
+"""
+import os
+import time
+import datetime
+import shutil
+from dotenv import load_dotenv
+from watchdog.observers import Observer
+from watchdog.events import FileSystemEventHandler
+from sphinx.cmd.build import main as sphinx_main
+
+
+def ensure_dir(file_path):
+    directory = os.path.dirname(file_path)
+    if not os.path.exists(directory):
+        os.makedirs(directory)
+
+
+def delete_dir_contents(directory):
+    if os.path.exists(directory):
+        shutil.rmtree(directory)
+
+
+class MyHandler(FileSystemEventHandler):
+
+    def __init__(self):
+        self.last_modified = datetime.datetime.now()
+
+    def on_any_event(self, event):
+        load_dotenv(override=True)
+        build_path = os.environ.get('BUILD_PATH', '_build')
+        if event is None:
+            print('initial build')
+        else:
+            print(f'event type: {event.event_type}  path : {event.src_path}')
+        if event is not None and (
+                datetime.datetime.now() - self.last_modified < datetime.timedelta(seconds=2)):
+            return
+        else:
+            self.last_modified = datetime.datetime.now()
+        argv = ['-b', 'html', '.', build_path]
+        ensure_dir(build_path)
+        delete_dir_contents(build_path)
+        # argv = ['-b', 'html', '-d', f'{build_path}/doctrees', '.', f'{build_path}/html']
+        sphinx_main(argv)
+        print('waiting for file changes. Press Ctrl+c to cancel.')
+
+
+if __name__ == "__main__":
+    event_handler = MyHandler()
+    event_handler.on_any_event(event=None)
+    observer = Observer()
+    observer.schedule(event_handler, path='.', recursive=True)
+    observer.start()
+
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        observer.stop()
+    observer.join()

docs/conf.py

@@ -14,7 +14,6 @@
 
 import sys
 import os
-import shlex
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -117,7 +116,24 @@
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#html_theme_options = {}
+html_theme_options = {
+    'description': 'Get the deep difference of any Python objects',
+    'show_powered_by': False,
+    'logo': 'logo_long_B1_black.svg',
+    'logo_name': 'Zepworks DeepDiff',
+    'analytics_id': 'UA-59104908-2',
+    'fixed_sidebar': True,
+    'extra_nav_links': {
+        'Zepworks': 'https://zepworks.com', 'Github': 'https://github.com/seperman/deepdiff'},
+    'show_relbars': True,
+    'github_repo': 'deepdiff',
+    'anchor': '#DDD',
+    'touch_icon': 'logo.svg',
+    'github_button': True,
+    'github_user': 'seperman',
+    'github_count': True,
+    'font_family': 'Open Sans',
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []
@@ -131,12 +147,12 @@
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = None
+html_logo = None
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-#html_favicon = None
+html_favicon = "./_static/favicon.ico"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

docs/deep_distance.rst

@@ -5,8 +5,10 @@
 Deep Distance
 =============
 
-The distance between 2 objects. A number between 0 and 1.
-Deep Distance in concept is inspired by Levenshtein Edit distance. At its core, the Deep Distance is the number of operations needed to convert one object to the other divided by the sum of the sizes of the 2 objects capped at 1. Note that it is the number of operations and NOT the "minimum" number of operations to convert one object to the other. The number is highly dependent on the granularity of the diff results controlled by the parameters passed to DeepDiff.
+
+Deep Distance is the distance between 2 objects. It is a floating point number between 0 and 1. Deep Distance in concept is inspired by `Levenshtein Edit Distance <https://en.wikipedia.org/wiki/Levenshtein_distance>`_.
+
+At its core, the Deep Distance is the number of operations needed to convert one object to the other divided by the sum of the sizes of the 2 objects capped at 1. Note that unlike Levensthtein Distance, the Deep Distance it is the based on the number of operations and NOT the “minimum” number of operations to convert one object to the other. The number is highly dependent on the granularity of the diff results. And the granularity is controlled by the parameters passed to DeepDiff.
 
 .. _get_deep_distance_label: