#33 rtd documentation

.gitignore

@@ -286,3 +286,6 @@ fabric.properties
 .vscode/*
 
 *.code-workspace
+
+## Sphinx Documentation ##
+docs/build

.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"

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
 

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"

docs/source/api/diffsync.diff.rst

@@ -0,0 +1,7 @@
+diffsync.diff
+=============
+
+.. automodule:: diffsync.diff
+ :members:
+ :undoc-members:
+ :show-inheritance:

docs/source/api/diffsync.enum.rst

@@ -0,0 +1,7 @@
+diffsync.enum
+=============
+
+.. automodule:: diffsync.enum
+ :members:
+ :undoc-members:
+ :show-inheritance:

docs/source/api/diffsync.exceptions.rst

@@ -0,0 +1,7 @@
+diffsync.exceptions
+===================
+
+.. automodule:: diffsync.exceptions
+ :members:
+ :undoc-members:
+ :show-inheritance:

docs/source/api/diffsync.helpers.rst

@@ -0,0 +1,7 @@
+diffsync.helpers
+================
+
+.. automodule:: diffsync.helpers
+ :members:
+ :undoc-members:
+ :show-inheritance:

docs/source/api/diffsync.logging.rst

@@ -0,0 +1,7 @@
+diffsync.logging
+================
+
+.. automodule:: diffsync.logging
+ :members:
+ :undoc-members:
+ :show-inheritance:

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

docs/source/api/diffsync.utils.rst

@@ -0,0 +1,7 @@
+diffsync.utils
+==============
+
+.. automodule:: diffsync.utils
+ :members:
+ :undoc-members:
+ :show-inheritance:

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)

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

docs/source/examples/02-callback-function.rst

@@ -0,0 +1,7 @@
+******************
+Callback Function
+******************
+
+.. mdinclude:: ../../../examples/example2/README.md
+ :start-line: 2
+ :end-line: 44

docs/source/examples/index.rst

@@ -0,0 +1,9 @@
+############
+Examples
+############
+
+.. toctree::
+ :maxdepth: 2
+
+ 01-multiple-data-sources
+ 02-callback-function

docs/source/getting_started/index.rst

@@ -0,0 +1,7 @@
+###############
+Getting Started
+###############
+
+.. mdinclude:: ../../../README.md
+ :start-line: 28
+ :end-line: 153

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`

docs/source/license/index.rst

@@ -0,0 +1,5 @@
+############
+License
+############
+
+.. mdinclude:: ../../../LICENSE

docs/source/overview/index.rst

@@ -0,0 +1,7 @@
+*********
+Overview
+*********
+
+.. mdinclude:: ../../../README.md
+ :start-line: 2
+ :end-line: 25

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;
+}

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;
+ }
+}

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 %}
+