Revert to sphinx

networktocode · dgarros · Oct 8, 2021 · Jun 21, 2021 · Jun 21, 2021 · Jun 21, 2021
commit 9885456560285fc1ee54efdd52131742b09be282
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -1,8 +1,9 @@
 ---
 version: 2
 
-mkdocs:
-  configuration: "mkdocs.yml"
+sphinx:
+  builder: "html"
+  configuration: "docs/source/conf.py"
   fail_on_warning: false
 
 python:

diff --git a/README.md b/README.md
@@ -1,5 +1,5 @@
 # DiffSync
-<!--intro start--> 
+
 DiffSync is a utility library that can be used to compare and synchronize different datasets.
 
 For example, it can be used to compare a list of devices from 2 inventory systems and, if required, synchronize them in either direction.
@@ -23,9 +23,9 @@ 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.
-<!--intro end-->
+
 # Getting started
-<!--getting started start-->
+
 To be able to properly compare different datasets, DiffSync relies on a shared data model that both systems must use.
 Specifically, each system or dataset must provide a `DiffSync` "adapter" subclass, which in turn represents its dataset as instances of one or more `DiffSyncModel` data model classes.
 
@@ -151,4 +151,3 @@ class BackendA(DiffSync):
         # The default DiffSync.sync_complete() method does nothing, but it's always a good habit to call super():
         super().sync_complete(source, diff, flags, logger)
 ```
-<!--getting started end-->
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/api_reference/diff/index.md b/docs/api_reference/diff/index.md
diff --git a/docs/api_reference/diffsync.md b/docs/api_reference/diffsync.md
diff --git a/docs/api_reference/diffsyncmodel.md b/docs/api_reference/diffsyncmodel.md
diff --git a/docs/api_reference/enum/index.md b/docs/api_reference/enum/index.md
diff --git a/docs/api_reference/exceptions/index.md b/docs/api_reference/exceptions/index.md
diff --git a/docs/api_reference/helpers/index.md b/docs/api_reference/helpers/index.md
diff --git a/docs/api_reference/logging/index.md b/docs/api_reference/logging/index.md
diff --git a/docs/api_reference/utils/index.md b/docs/api_reference/utils/index.md
diff --git a/docs/examples/example1.md b/docs/examples/example1.md
diff --git a/docs/examples/example2.md b/docs/examples/example2.md
diff --git a/docs/extra.css b/docs/extra.css
diff --git a/docs/getting_started.md b/docs/getting_started.md
diff --git a/docs/index.md b/docs/index.md
diff --git a/docs/license.md b/docs/license.md
diff --git a/docs/source/api/diffsync.rst b/docs/source/api/diffsync.rst
@@ -0,0 +1,56 @@
+API Reference
+=============
+
+.. automodule:: diffsync
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+diffsync.diff
+-------------
+
+.. automodule:: diffsync.diff
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+diffsync.enum
+-------------
+
+.. automodule:: diffsync.enum
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+diffsync.exceptions
+-------------------
+
+.. automodule:: diffsync.exceptions
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+diffsync.helpers
+----------------
+
+.. automodule:: diffsync.helpers
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+diffsync.logging
+----------------
+
+.. automodule:: diffsync.logging
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+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(["-MTf", "-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