Merge pull request #59 from josh5276/#33-rtd-documentation

dgarros · web-flow · commit 3c3060f2c137 · 2021-10-08T13:52:21.000-04:00
#33 rtd documentation
diff --git a/.gitignore b/.gitignore
@@ -286,3 +286,6 @@ fabric.properties
 .vscode/*
 
 *.code-workspace
+
+## Sphinx Documentation ##
+docs/build
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -0,0 +1,15 @@
+---
+version: 2
+
+sphinx:
+  builder: "html"
+  configuration: "docs/source/conf.py"
+  fail_on_warning: false
+
+python:
+  version: 3.7
+  install:
+    - method: "pip"
+      path: "."
+      extra_requirements:
+        - "docs"
diff --git a/README.md b/README.md
@@ -22,7 +22,7 @@ A.sync_from(B)
 A.sync_to(B)
 ```
 
-You may wish to peruse the [`diffsync` GitHub topic](https://github.com/topics/diffsync) for examples of projects using this library.
+You may wish to peruse the `diffsync` [GitHub topic](https://github.com/topics/diffsync) for examples of projects using this library.
 
 # Getting started
 
diff --git a/diffsync/__init__.py b/diffsync/__init__.py
@@ -37,7 +37,7 @@ class DiffSyncModel(BaseModel):
     This class has several underscore-prefixed class variables that subclasses should set as desired; see below.
 
     NOTE: The groupings _identifiers, _attributes, and _children are mutually exclusive; any given field name can
-          be included in **at most** one of these three tuples.
+    be included in **at most** one of these three tuples.
     """
 
     _modelname: ClassVar[str] = "diffsyncmodel"
diff --git a/docs/source/api/diffsync.diff.rst b/docs/source/api/diffsync.diff.rst
@@ -0,0 +1,7 @@
+diffsync.diff
+=============
+
+.. automodule:: diffsync.diff
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/api/diffsync.enum.rst b/docs/source/api/diffsync.enum.rst
@@ -0,0 +1,7 @@
+diffsync.enum
+=============
+
+.. automodule:: diffsync.enum
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/api/diffsync.exceptions.rst b/docs/source/api/diffsync.exceptions.rst
@@ -0,0 +1,7 @@
+diffsync.exceptions
+===================
+
+.. automodule:: diffsync.exceptions
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/api/diffsync.helpers.rst b/docs/source/api/diffsync.helpers.rst
@@ -0,0 +1,7 @@
+diffsync.helpers
+================
+
+.. automodule:: diffsync.helpers
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/api/diffsync.logging.rst b/docs/source/api/diffsync.logging.rst
@@ -0,0 +1,7 @@
+diffsync.logging
+================
+
+.. automodule:: diffsync.logging
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/api/diffsync.rst b/docs/source/api/diffsync.rst
@@ -0,0 +1,18 @@
+API Reference
+=============
+
+.. automodule:: diffsync
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+.. toctree::
+   :maxdepth: 4
+
+   diffsync.diff
+   diffsync.enum
+   diffsync.exceptions
+   diffsync.helpers
+   diffsync.logging
+   diffsync.utils
diff --git a/docs/source/api/diffsync.utils.rst b/docs/source/api/diffsync.utils.rst
@@ -0,0 +1,7 @@
+diffsync.utils
+==============
+
+.. automodule:: diffsync.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -0,0 +1,99 @@
+"""Configuration file for the Sphinx documentation builder.
+
+This file only contains a selection of the most common options. For a full
+list see the documentation:
+https://www.sphinx-doc.org/en/master/usage/configuration.html
+"""
+
+# -- Path setup --------------------------------------------------------------
+
+# 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
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+# pylint: disable=W,C,R
+import os
+import sys
+
+from pathlib import Path
+from sphinx.ext.apidoc import main
+
+try:
+    import toml
+except ImportError:
+    sys.exit("Please make sure to `pip install toml` or enable the Poetry shell and run `poetry install`.")
+
+# -- Variable setup --------------------------------------------------------------
+
+ROOT_DIR = Path(__file__).parent.parent.parent
+CURR_DIR = f"{ROOT_DIR}/docs/source"
+PYPROJECT_CONFIG = toml.load(f"{ROOT_DIR}/pyproject.toml")
+TOOL_CONFIG = PYPROJECT_CONFIG["tool"]["poetry"]
+
+# Inserts the diffsync library into the path. This is needed for RTD env to find the
+# library needed for autodocs.
+sys.path.insert(0, os.path.abspath("../.."))
+
+# -- Project information -----------------------------------------------------
+
+project = TOOL_CONFIG["name"]
+copyright = f"2020-2021, {','.join(TOOL_CONFIG['authors'])}"
+author = ",".join(TOOL_CONFIG["authors"])
+
+# The full version, including alpha/beta/rc tags
+release = TOOL_CONFIG["version"]
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "m2r2"]
+
+autodoc_default_options = {
+    "members": True,
+    "show-inheritance": True,
+    "special-members": "__init__",
+    "undoc-members": True,
+}
+
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# 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,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["static"]
+
+
+def remove_module_docstring(app, what, name, obj, options, lines):
+    """Removes copyright heading on modules to prevent unneeded reference in the API documentation."""
+    if what == "module":
+        # At the module level, remove everything except the first line containing a summary of the module. All
+        # lines that follow are copyright notices.
+        del lines[1:]
+
+
+def run_apidoc(_):
+    """Adds the sphinx-apidoc command as a callback during the build process."""
+    main(["-MTfe", "-t", f"{CURR_DIR}/template/api", "-o", f"{CURR_DIR}/api", f"{ROOT_DIR}/{TOOL_CONFIG['name']}"])
+
+
+def setup(app):
+    """Registers the callbacks to be called when the event is emitted."""
+    app.connect("builder-inited", run_apidoc)
+    app.connect("autodoc-process-docstring", remove_module_docstring)
diff --git a/docs/source/examples/01-multiple-data-sources.rst b/docs/source/examples/01-multiple-data-sources.rst
@@ -0,0 +1,7 @@
+****************************
+Using Multiple Data Sources
+****************************
+
+.. mdinclude:: ../../../examples/example1/README.md
+   :start-line: 2
+   :end-line: 67
diff --git a/docs/source/examples/02-callback-function.rst b/docs/source/examples/02-callback-function.rst
@@ -0,0 +1,7 @@
+******************
+Callback Function
+******************
+
+.. mdinclude:: ../../../examples/example2/README.md
+   :start-line: 2
+   :end-line: 44
diff --git a/docs/source/examples/index.rst b/docs/source/examples/index.rst
@@ -0,0 +1,9 @@
+############
+Examples
+############
+
+.. toctree::
+   :maxdepth: 2
+
+   01-multiple-data-sources
+   02-callback-function
diff --git a/docs/source/getting_started/index.rst b/docs/source/getting_started/index.rst
@@ -0,0 +1,7 @@
+###############
+Getting Started
+###############
+
+.. mdinclude:: ../../../README.md
+   :start-line: 28
+   :end-line: 153
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -0,0 +1,20 @@
+Welcome to DiffSync's documentation!
+====================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   overview/index
+   getting_started/index
+   examples/index
+   api/diffsync
+   license/index
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
diff --git a/docs/source/license/index.rst b/docs/source/license/index.rst
@@ -0,0 +1,5 @@
+############
+License
+############
+
+.. mdinclude:: ../../../LICENSE
diff --git a/docs/source/overview/index.rst b/docs/source/overview/index.rst
@@ -0,0 +1,7 @@
+*********
+Overview
+*********
+
+.. mdinclude:: ../../../README.md
+   :start-line: 2
+   :end-line: 25
diff --git a/docs/source/static/schema-page.css b/docs/source/static/schema-page.css
@@ -0,0 +1,62 @@
+body {
+  font-family: 'Fira Sans', 'Noto Sans', 'Source Sans Pro', 'Segoe UI', Roboto, 'Lucida Sans Unicode', 'Lucida Grande', 'DejaVu Sans', sans-serif;
+}
+@media (min-width: 60em) {
+  body {
+    display: flex;
+    flex-direction: row;
+  }
+}
+#jschemer-nav {
+  min-width: 15rem;
+  padding: 1em;
+}
+.jschemer-schema {
+  border: 0.05em solid #CCC;
+  border-radius: 0.25em;
+  margin: 0.5em;
+  max-width: 60em;
+  padding: 1em;
+}
+.jschemer-schema code,
+.jschemer-schema pre {
+  background-color: rgba(27, 31, 35, 0.05);
+  border-radius: 0.1em;
+  font-size: 85%;
+  line-height: 1.5;
+}
+.jschemer-schema pre {
+  padding: 1em 0.5em;
+}
+.jschemer-schema code {
+  display: inline;
+  font-family: 'Fira Mono', 'Noto Mono', 'Source Code Pro', Consolas, 'Roboto Mono', 'Lucida Console', Monaco, 'DejaVu Sans Mono', monospace;
+  font-size: 85%;
+  line-height: inherit;
+  padding: 0.2em 0.4em;
+  word-wrap: normal;
+}
+.jschemer-schema pre > code {
+  background-color: transparent;
+  padding: 0;
+}
+.jschemer-schema h1 {
+  display: inline;
+  font-size: 1.5em;
+  vertical-align: middle;
+}
+.jschemer-schema h1 code::before {
+  content: '"';
+}
+.jschemer-schema h1 code::after {
+  content: '"';
+}
+.jschemer-schema h2 {
+  font-size: 1em;
+}
+main > .jschemer-schema > details > summary > h1 {
+  font-size: 2em;
+}
+main ul {
+  list-style: disc;
+}
diff --git a/docs/source/static/theme_overrides.css b/docs/source/static/theme_overrides.css
@@ -0,0 +1,13 @@
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+
+   .wy-table-responsive table td {
+      /* !important prevents the common CSS stylesheets from overriding
+         this as on RTD they are loaded after this stylesheet */
+      white-space: normal !important;
+   }
+
+   .wy-table-responsive {
+      overflow: visible !important;
+   }
+}
diff --git a/docs/source/template/api/module.rst_t b/docs/source/template/api/module.rst_t
@@ -0,0 +1,9 @@
+{%- if show_headings %}
+{{- basename | e | heading }}
+
+{% endif -%}
+.. automodule:: {{ qualname }}
+{%- for option in automodule_options %}
+   :{{ option }}:
+{%- endfor %}
+
diff --git a/docs/source/template/api/package.rst_t b/docs/source/template/api/package.rst_t
diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml
diff --git a/tasks.py b/tasks.py
