From 558f58ccf01f2080db567cc33b518a3b8c31eed7 Mon Sep 17 00:00:00 2001 From: Josh Silvas Date: Mon, 21 Jun 2021 11:59:10 -0500 Subject: [PATCH 01/22] Adds RTD files and dependencies --- .readthedocs.yml | 8 + docs/source/api/diffsync.rst | 56 ++++ docs/source/conf.py | 87 ++++++ docs/source/examples/example1.rst | 7 + docs/source/examples/example2.rst | 7 + docs/source/examples/index.rst | 9 + docs/source/getting_started/index.rst | 7 + docs/source/index.rst | 20 ++ docs/source/license/index.rst | 5 + docs/source/overview/index.rst | 7 + docs/source/static/schema-page.css | 62 ++++ docs/source/static/theme_overrides.css | 13 + docs/source/template/api/package.rst_t | 51 ++++ poetry.lock | 403 ++++++++++++++++++++++++- pyproject.toml | 3 + 15 files changed, 744 insertions(+), 1 deletion(-) create mode 100644 .readthedocs.yml create mode 100644 docs/source/api/diffsync.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/examples/example1.rst create mode 100644 docs/source/examples/example2.rst create mode 100644 docs/source/examples/index.rst create mode 100644 docs/source/getting_started/index.rst create mode 100644 docs/source/index.rst create mode 100644 docs/source/license/index.rst create mode 100644 docs/source/overview/index.rst create mode 100644 docs/source/static/schema-page.css create mode 100644 docs/source/static/theme_overrides.css create mode 100644 docs/source/template/api/package.rst_t diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 00000000..70f6983d --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,8 @@ +--- +version: 2 + +sphinx: + builder: "html" + configuration: "docs/source/conf.py" + fail_on_warning: false + diff --git a/docs/source/api/diffsync.rst b/docs/source/api/diffsync.rst new file mode 100644 index 00000000..473420e9 --- /dev/null +++ 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 new file mode 100644 index 00000000..a24979e7 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,87 @@ +# 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. +# +import os +import sys + +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 -------------------------------------------------------------- + +PYPROJECT_CONFIG = toml.load(f"{os.path.dirname(os.path.dirname(os.getcwd()))}/pyproject.toml") +TOOL_CONFIG = PYPROJECT_CONFIG["tool"]["poetry"] + +# -- Project information ----------------------------------------------------- + +project = TOOL_CONFIG["name"] +copyright = f"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 information at the top of each module 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 setup(app): + app.connect("autodoc-process-docstring", remove_module_docstring) diff --git a/docs/source/examples/example1.rst b/docs/source/examples/example1.rst new file mode 100644 index 00000000..2e9448b1 --- /dev/null +++ b/docs/source/examples/example1.rst @@ -0,0 +1,7 @@ +********* +Example 1 +********* + +.. mdinclude:: ../../../examples/example1/README.md + :start-line: 2 + :end-line: 67 \ No newline at end of file diff --git a/docs/source/examples/example2.rst b/docs/source/examples/example2.rst new file mode 100644 index 00000000..92e263b9 --- /dev/null +++ b/docs/source/examples/example2.rst @@ -0,0 +1,7 @@ +********* +Example 2 +********* + +.. mdinclude:: ../../../examples/example2/README.md + :start-line: 2 + :end-line: 44 \ No newline at end of file diff --git a/docs/source/examples/index.rst b/docs/source/examples/index.rst new file mode 100644 index 00000000..3dc70da2 --- /dev/null +++ b/docs/source/examples/index.rst @@ -0,0 +1,9 @@ +############ +Examples +############ + +.. toctree:: + :maxdepth: 2 + + example1 + example2 \ No newline at end of file diff --git a/docs/source/getting_started/index.rst b/docs/source/getting_started/index.rst new file mode 100644 index 00000000..35b05952 --- /dev/null +++ b/docs/source/getting_started/index.rst @@ -0,0 +1,7 @@ +############ +Getting Started +############ + +.. mdinclude:: ../../../README.md + :start-line: 28 + :end-line: 153 \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..6d4d2c6d --- /dev/null +++ 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 new file mode 100644 index 00000000..112bcdff --- /dev/null +++ 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 new file mode 100644 index 00000000..89a03204 --- /dev/null +++ b/docs/source/overview/index.rst @@ -0,0 +1,7 @@ +********* +Overview +********* + +.. mdinclude:: ../../../README.md + :start-line: 2 + :end-line: 25 \ No newline at end of file diff --git a/docs/source/static/schema-page.css b/docs/source/static/schema-page.css new file mode 100644 index 00000000..78f9f02c --- /dev/null +++ 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; +} \ No newline at end of file diff --git a/docs/source/static/theme_overrides.css b/docs/source/static/theme_overrides.css new file mode 100644 index 00000000..63ee6cc7 --- /dev/null +++ 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/package.rst_t b/docs/source/template/api/package.rst_t new file mode 100644 index 00000000..621e6ea4 --- /dev/null +++ b/docs/source/template/api/package.rst_t @@ -0,0 +1,51 @@ +{%- macro automodule(modname, options) -%} +.. automodule:: {{ modname }} +{%- for option in options %} + :{{ option }}: +{%- endfor %} +{%- endmacro %} + +{%- macro toctree(docnames) -%} +.. toctree:: + :maxdepth: {{ maxdepth }} +{% for docname in docnames %} + {{ docname }} +{%- endfor %} +{%- endmacro %} + +{%- if is_namespace %} +{{- pkgname | e | heading | title }} +{% else %} +{{- "API Reference" | e | heading }} +{% endif %} + +{%- if modulefirst and not is_namespace %} +{{ automodule(pkgname, automodule_options) }} +{% endif %} + +{%- if subpackages %} +Subpackages +----------- + +{{ toctree(subpackages) }} +{% endif %} + +{%- if submodules %} +{% if separatemodules %} +{{ toctree(submodules) }} +{% else %} +{%- for submodule in submodules %} +{% if show_headings %} +{{- submodule | e | heading(2) }} +{% endif %} +{{ automodule(submodule, automodule_options) }} +{% endfor %} +{%- endif %} +{%- endif %} + +{%- if not modulefirst and not is_namespace %} +Module contents +--------------- + +{{ automodule(pkgname, automodule_options) }} +{% endif %} \ No newline at end of file diff --git a/poetry.lock b/poetry.lock index b6a5a2d6..3d5d6eaa 100644 --- a/poetry.lock +++ b/poetry.lock @@ -1,3 +1,11 @@ +[[package]] +name = "alabaster" +version = "0.7.12" +description = "A configurable sidebar-enabled Sphinx theme" +category = "dev" +optional = false +python-versions = "*" + [[package]] name = "appdirs" version = "1.4.4" @@ -42,6 +50,17 @@ docs = ["furo", "sphinx", "zope.interface"] tests = ["coverage[toml] (>=5.0.2)", "hypothesis", "pympler", "pytest (>=4.3.0)", "six", "zope.interface"] tests_no_zope = ["coverage[toml] (>=5.0.2)", "hypothesis", "pympler", "pytest (>=4.3.0)", "six"] +[[package]] +name = "babel" +version = "2.9.1" +description = "Internationalization utilities" +category = "dev" +optional = false +python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*" + +[package.dependencies] +pytz = ">=2015.7" + [[package]] name = "bandit" version = "1.6.3" @@ -77,6 +96,22 @@ typed-ast = ">=1.4.0" [package.extras] d = ["aiohttp (>=3.3.2)", "aiohttp-cors"] +[[package]] +name = "certifi" +version = "2021.5.30" +description = "Python package for providing Mozilla's CA Bundle." +category = "dev" +optional = false +python-versions = "*" + +[[package]] +name = "chardet" +version = "4.0.0" +description = "Universal encoding detector for Python 2 and 3" +category = "dev" +optional = false +python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*" + [[package]] name = "click" version = "7.1.2" @@ -115,6 +150,14 @@ category = "main" optional = false python-versions = ">=3.6, <3.7" +[[package]] +name = "docutils" +version = "0.16" +description = "Docutils -- Python Documentation Utilities" +category = "dev" +optional = false +python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*" + [[package]] name = "flake8" version = "3.8.4" @@ -151,6 +194,22 @@ python-versions = ">=3.4" [package.dependencies] gitdb = ">=4.0.1,<5" +[[package]] +name = "idna" +version = "2.10" +description = "Internationalized Domain Names in Applications (IDNA)" +category = "dev" +optional = false +python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*" + +[[package]] +name = "imagesize" +version = "1.2.0" +description = "Getting image size from png/jpeg/jpeg2000/gif file" +category = "dev" +optional = false +python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*" + [[package]] name = "importlib-metadata" version = "3.1.1" @@ -195,6 +254,20 @@ pipfile_deprecated_finder = ["pipreqs", "requirementslib"] requirements_deprecated_finder = ["pipreqs", "pip-api"] colors = ["colorama (>=0.4.3,<0.5.0)"] +[[package]] +name = "jinja2" +version = "3.0.1" +description = "A very fast and expressive template engine." +category = "dev" +optional = false +python-versions = ">=3.6" + +[package.dependencies] +MarkupSafe = ">=2.0" + +[package.extras] +i18n = ["Babel (>=2.7)"] + [[package]] name = "lazy-object-proxy" version = "1.4.3" @@ -203,6 +276,26 @@ category = "dev" optional = false python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*" +[[package]] +name = "m2r2" +version = "0.2.7" +description = "Markdown and reStructuredText in a single file." +category = "dev" +optional = false +python-versions = "*" + +[package.dependencies] +docutils = "*" +mistune = "*" + +[[package]] +name = "markupsafe" +version = "2.0.1" +description = "Safely add untrusted strings to HTML/XML markup." +category = "dev" +optional = false +python-versions = ">=3.6" + [[package]] name = "mccabe" version = "0.6.1" @@ -211,6 +304,14 @@ category = "dev" optional = false python-versions = "*" +[[package]] +name = "mistune" +version = "0.8.4" +description = "The fastest markdown parser in pure Python" +category = "dev" +optional = false +python-versions = "*" + [[package]] name = "mypy" version = "0.782" @@ -327,6 +428,14 @@ category = "dev" optional = false python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*" +[[package]] +name = "pygments" +version = "2.9.0" +description = "Pygments is a syntax highlighting package written in Python." +category = "dev" +optional = false +python-versions = ">=3.5" + [[package]] name = "pylint" version = "2.6.0" @@ -400,6 +509,14 @@ python-versions = "*" pytest = "*" structlog = "*" +[[package]] +name = "pytz" +version = "2021.1" +description = "World timezone definitions, modern and historical" +category = "dev" +optional = false +python-versions = "*" + [[package]] name = "pyyaml" version = "5.3.1" @@ -416,6 +533,24 @@ category = "dev" optional = false python-versions = "*" +[[package]] +name = "requests" +version = "2.25.1" +description = "Python HTTP for Humans." +category = "dev" +optional = false +python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*" + +[package.dependencies] +certifi = ">=2017.4.17" +chardet = ">=3.0.2,<5" +idna = ">=2.5,<3" +urllib3 = ">=1.21.1,<1.27" + +[package.extras] +security = ["pyOpenSSL (>=0.14)", "cryptography (>=1.3.4)"] +socks = ["PySocks (>=1.5.6,!=1.5.7)", "win-inet-pton"] + [[package]] name = "six" version = "1.15.0" @@ -440,6 +575,123 @@ category = "dev" optional = false python-versions = "*" +[[package]] +name = "sphinx" +version = "4.0.2" +description = "Python documentation generator" +category = "dev" +optional = false +python-versions = ">=3.6" + +[package.dependencies] +alabaster = ">=0.7,<0.8" +babel = ">=1.3" +colorama = {version = ">=0.3.5", markers = "sys_platform == \"win32\""} +docutils = ">=0.14,<0.18" +imagesize = "*" +Jinja2 = ">=2.3" +packaging = "*" +Pygments = ">=2.0" +requests = ">=2.5.0" +snowballstemmer = ">=1.1" +sphinxcontrib-applehelp = "*" +sphinxcontrib-devhelp = "*" +sphinxcontrib-htmlhelp = "*" +sphinxcontrib-jsmath = "*" +sphinxcontrib-qthelp = "*" +sphinxcontrib-serializinghtml = "*" + +[package.extras] +docs = ["sphinxcontrib-websupport"] +lint = ["flake8 (>=3.5.0)", "isort", "mypy (>=0.800)", "docutils-stubs"] +test = ["pytest", "pytest-cov", "html5lib", "cython", "typed-ast"] + +[[package]] +name = "sphinx-rtd-theme" +version = "0.5.2" +description = "Read the Docs theme for Sphinx" +category = "dev" +optional = false +python-versions = "*" + +[package.dependencies] +docutils = "<0.17" +sphinx = "*" + +[package.extras] +dev = ["transifex-client", "sphinxcontrib-httpdomain", "bump2version"] + +[[package]] +name = "sphinxcontrib-applehelp" +version = "1.0.2" +description = "sphinxcontrib-applehelp is a sphinx extension which outputs Apple help books" +category = "dev" +optional = false +python-versions = ">=3.5" + +[package.extras] +lint = ["flake8", "mypy", "docutils-stubs"] +test = ["pytest"] + +[[package]] +name = "sphinxcontrib-devhelp" +version = "1.0.2" +description = "sphinxcontrib-devhelp is a sphinx extension which outputs Devhelp document." +category = "dev" +optional = false +python-versions = ">=3.5" + +[package.extras] +lint = ["flake8", "mypy", "docutils-stubs"] +test = ["pytest"] + +[[package]] +name = "sphinxcontrib-htmlhelp" +version = "2.0.0" +description = "sphinxcontrib-htmlhelp is a sphinx extension which renders HTML help files" +category = "dev" +optional = false +python-versions = ">=3.6" + +[package.extras] +lint = ["flake8", "mypy", "docutils-stubs"] +test = ["pytest", "html5lib"] + +[[package]] +name = "sphinxcontrib-jsmath" +version = "1.0.1" +description = "A sphinx extension which renders display math in HTML via JavaScript" +category = "dev" +optional = false +python-versions = ">=3.5" + +[package.extras] +test = ["pytest", "flake8", "mypy"] + +[[package]] +name = "sphinxcontrib-qthelp" +version = "1.0.3" +description = "sphinxcontrib-qthelp is a sphinx extension which outputs QtHelp document." +category = "dev" +optional = false +python-versions = ">=3.5" + +[package.extras] +lint = ["flake8", "mypy", "docutils-stubs"] +test = ["pytest"] + +[[package]] +name = "sphinxcontrib-serializinghtml" +version = "1.1.5" +description = "sphinxcontrib-serializinghtml is a sphinx extension which outputs \"serialized\" HTML files (json and pickle)." +category = "dev" +optional = false +python-versions = ">=3.5" + +[package.extras] +lint = ["flake8", "mypy", "docutils-stubs"] +test = ["pytest"] + [[package]] name = "stevedore" version = "3.3.0" @@ -493,6 +745,19 @@ category = "dev" optional = false python-versions = "*" +[[package]] +name = "urllib3" +version = "1.26.5" +description = "HTTP library with thread-safe connection pooling, file post, and more." +category = "dev" +optional = false +python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, <4" + +[package.extras] +brotli = ["brotlipy (>=0.6.0)"] +secure = ["pyOpenSSL (>=0.14)", "cryptography (>=1.3.4)", "idna (>=2.0.0)", "certifi", "ipaddress"] +socks = ["PySocks (>=1.5.6,!=1.5.7,<2.0)"] + [[package]] name = "wrapt" version = "1.12.1" @@ -528,9 +793,13 @@ testing = ["pytest (>=3.5,!=3.7.3)", "pytest-checkdocs (>=1.2.3)", "pytest-flake [metadata] lock-version = "1.1" python-versions = "^3.6" -content-hash = "a967b3ed0beeb5ecb6a3674550401f23cdcd649dbcaa54300d609b74a957d0bd" +content-hash = "479de3df9b86abb75fc2136a6ecbaf7f02a5ccd62f35ffee6a99b36f998f3126" [metadata.files] +alabaster = [ + {file = "alabaster-0.7.12-py2.py3-none-any.whl", hash = "sha256:446438bdcca0e05bd45ea2de1668c1d9b032e1a9154c2c259092d77031ddd359"}, + {file = "alabaster-0.7.12.tar.gz", hash = "sha256:a661d72d58e6ea8a57f7a86e37d86716863ee5e92788398526d58b26a4e4dc02"}, +] appdirs = [ {file = "appdirs-1.4.4-py2.py3-none-any.whl", hash = "sha256:a841dacd6b99318a741b166adb07e19ee71a274450e68237b4650ca1055ab128"}, {file = "appdirs-1.4.4.tar.gz", hash = "sha256:7d5d0167b2b1ba821647616af46a749d1c653740dd0d2415100fe26e27afdf41"}, @@ -547,6 +816,10 @@ attrs = [ {file = "attrs-20.3.0-py2.py3-none-any.whl", hash = "sha256:31b2eced602aa8423c2aea9c76a724617ed67cf9513173fd3a4f03e3a929c7e6"}, {file = "attrs-20.3.0.tar.gz", hash = "sha256:832aa3cde19744e49938b91fea06d69ecb9e649c93ba974535d08ad92164f700"}, ] +babel = [ + {file = "Babel-2.9.1-py2.py3-none-any.whl", hash = "sha256:ab49e12b91d937cd11f0b67cb259a57ab4ad2b59ac7a3b41d6c06c0ac5b0def9"}, + {file = "Babel-2.9.1.tar.gz", hash = "sha256:bc0c176f9f6a994582230df350aa6e05ba2ebe4b3ac317eab29d9be5d2768da0"}, +] bandit = [ {file = "bandit-1.6.3-py2.py3-none-any.whl", hash = "sha256:2ff3fe35fe3212c0be5fc9c4899bd0108e2b5239c5ff62fb174639e4660fe958"}, {file = "bandit-1.6.3.tar.gz", hash = "sha256:d02dfe250f4aa2d166c127ad81d192579e2bfcdb8501717c0e2005e35a6bcf60"}, @@ -555,6 +828,14 @@ black = [ {file = "black-19.10b0-py36-none-any.whl", hash = "sha256:1b30e59be925fafc1ee4565e5e08abef6b03fe455102883820fe5ee2e4734e0b"}, {file = "black-19.10b0.tar.gz", hash = "sha256:c2edb73a08e9e0e6f65a0e6af18b059b8b1cdd5bef997d7a0b181df93dc81539"}, ] +certifi = [ + {file = "certifi-2021.5.30-py2.py3-none-any.whl", hash = "sha256:50b1e4f8446b06f41be7dd6338db18e0990601dce795c2b1686458aa7e8fa7d8"}, + {file = "certifi-2021.5.30.tar.gz", hash = "sha256:2bbf76fd432960138b3ef6dda3dde0544f27cbf8546c458e60baf371917ba9ee"}, +] +chardet = [ + {file = "chardet-4.0.0-py2.py3-none-any.whl", hash = "sha256:f864054d66fd9118f2e67044ac8981a54775ec5b67aed0441892edb553d21da5"}, + {file = "chardet-4.0.0.tar.gz", hash = "sha256:0d6f53a15db4120f2b08c94f11e7d93d2c911ee118b6b30a04ec3ee8310179fa"}, +] click = [ {file = "click-7.1.2-py2.py3-none-any.whl", hash = "sha256:dacca89f4bfadd5de3d7489b7c8a566eee0d3676333fbb50030263894c38c0dc"}, {file = "click-7.1.2.tar.gz", hash = "sha256:d2b5255c7c6349bc1bd1e59e08cd12acbbd63ce649f2588755783aa94dfb6b1a"}, @@ -603,6 +884,10 @@ dataclasses = [ {file = "dataclasses-0.7-py3-none-any.whl", hash = "sha256:3459118f7ede7c8bea0fe795bff7c6c2ce287d01dd226202f7c9ebc0610a7836"}, {file = "dataclasses-0.7.tar.gz", hash = "sha256:494a6dcae3b8bcf80848eea2ef64c0cc5cd307ffc263e17cdf42f3e5420808e6"}, ] +docutils = [ + {file = "docutils-0.16-py2.py3-none-any.whl", hash = "sha256:0c5b78adfbf7762415433f5515cd5c9e762339e23369dbe8000d84a4bf4ab3af"}, + {file = "docutils-0.16.tar.gz", hash = "sha256:c2de3a60e9e7d07be26b7f2b00ca0309c207e06c100f9cc2a94931fc75a478fc"}, +] flake8 = [ {file = "flake8-3.8.4-py2.py3-none-any.whl", hash = "sha256:749dbbd6bfd0cf1318af27bf97a14e28e5ff548ef8e5b1566ccfb25a11e7c839"}, {file = "flake8-3.8.4.tar.gz", hash = "sha256:aadae8761ec651813c24be05c6f7b4680857ef6afaae4651a4eccaef97ce6c3b"}, @@ -615,11 +900,20 @@ gitpython = [ {file = "GitPython-3.1.11-py3-none-any.whl", hash = "sha256:6eea89b655917b500437e9668e4a12eabdcf00229a0df1762aabd692ef9b746b"}, {file = "GitPython-3.1.11.tar.gz", hash = "sha256:befa4d101f91bad1b632df4308ec64555db684c360bd7d2130b4807d49ce86b8"}, ] +idna = [ + {file = "idna-2.10-py2.py3-none-any.whl", hash = "sha256:b97d804b1e9b523befed77c48dacec60e6dcb0b5391d57af6a65a312a90648c0"}, + {file = "idna-2.10.tar.gz", hash = "sha256:b307872f855b18632ce0c21c5e45be78c0ea7ae4c15c828c20788b26921eb3f6"}, +] +imagesize = [ + {file = "imagesize-1.2.0-py2.py3-none-any.whl", hash = "sha256:6965f19a6a2039c7d48bca7dba2473069ff854c36ae6f19d2cde309d998228a1"}, + {file = "imagesize-1.2.0.tar.gz", hash = "sha256:b1f6b5a4eab1f73479a50fb79fcf729514a900c341d8503d62a62dbc4127a2b1"}, +] importlib-metadata = [ {file = "importlib_metadata-3.1.1-py3-none-any.whl", hash = "sha256:6112e21359ef8f344e7178aa5b72dc6e62b38b0d008e6d3cb212c5b84df72013"}, {file = "importlib_metadata-3.1.1.tar.gz", hash = "sha256:b0c2d3b226157ae4517d9625decf63591461c66b3a808c2666d538946519d170"}, ] iniconfig = [ + {file = "iniconfig-1.1.1-py2.py3-none-any.whl", hash = "sha256:011e24c64b7f47f6ebd835bb12a743f2fbe9a26d4cecaa7f53bc4f35ee9da8b3"}, {file = "iniconfig-1.1.1.tar.gz", hash = "sha256:bc3af051d7d14b2ee5ef9969666def0cd1a000e121eaea580d4a313df4b37f32"}, ] invoke = [ @@ -631,6 +925,10 @@ isort = [ {file = "isort-5.6.4-py3-none-any.whl", hash = "sha256:dcab1d98b469a12a1a624ead220584391648790275560e1a43e54c5dceae65e7"}, {file = "isort-5.6.4.tar.gz", hash = "sha256:dcaeec1b5f0eca77faea2a35ab790b4f3680ff75590bfcb7145986905aab2f58"}, ] +jinja2 = [ + {file = "Jinja2-3.0.1-py3-none-any.whl", hash = "sha256:1f06f2da51e7b56b8f238affdd6b4e2c61e39598a378cc49345bc1bd42a978a4"}, + {file = "Jinja2-3.0.1.tar.gz", hash = "sha256:703f484b47a6af502e743c9122595cc812b0271f661722403114f71a79d0f5a4"}, +] lazy-object-proxy = [ {file = "lazy-object-proxy-1.4.3.tar.gz", hash = "sha256:f3900e8a5de27447acbf900b4750b0ddfd7ec1ea7fbaf11dfa911141bc522af0"}, {file = "lazy_object_proxy-1.4.3-cp27-cp27m-macosx_10_13_x86_64.whl", hash = "sha256:a2238e9d1bb71a56cd710611a1614d1194dc10a175c1e08d75e1a7bcc250d442"}, @@ -654,10 +952,54 @@ lazy-object-proxy = [ {file = "lazy_object_proxy-1.4.3-cp38-cp38-win32.whl", hash = "sha256:5541cada25cd173702dbd99f8e22434105456314462326f06dba3e180f203dfd"}, {file = "lazy_object_proxy-1.4.3-cp38-cp38-win_amd64.whl", hash = "sha256:59f79fef100b09564bc2df42ea2d8d21a64fdcda64979c0fa3db7bdaabaf6239"}, ] +m2r2 = [ + {file = "m2r2-0.2.7-py3-none-any.whl", hash = "sha256:a1b87b00f4d5163a3616253fca4c045f8351818cd803ba2e24af8897442a0eae"}, + {file = "m2r2-0.2.7.tar.gz", hash = "sha256:fbf72ade9f648d41658f97c5267687431612451f36b65761a138fbc276294df5"}, +] +markupsafe = [ + {file = "MarkupSafe-2.0.1-cp36-cp36m-macosx_10_9_x86_64.whl", hash = "sha256:f9081981fe268bd86831e5c75f7de206ef275defcb82bc70740ae6dc507aee51"}, + {file = "MarkupSafe-2.0.1-cp36-cp36m-manylinux1_i686.whl", hash = "sha256:0955295dd5eec6cb6cc2fe1698f4c6d84af2e92de33fbcac4111913cd100a6ff"}, + {file = "MarkupSafe-2.0.1-cp36-cp36m-manylinux1_x86_64.whl", hash = "sha256:0446679737af14f45767963a1a9ef7620189912317d095f2d9ffa183a4d25d2b"}, + {file = "MarkupSafe-2.0.1-cp36-cp36m-manylinux2010_i686.whl", hash = "sha256:f826e31d18b516f653fe296d967d700fddad5901ae07c622bb3705955e1faa94"}, + {file = "MarkupSafe-2.0.1-cp36-cp36m-manylinux2010_x86_64.whl", hash = "sha256:fa130dd50c57d53368c9d59395cb5526eda596d3ffe36666cd81a44d56e48872"}, + {file = "MarkupSafe-2.0.1-cp36-cp36m-manylinux2014_aarch64.whl", hash = "sha256:905fec760bd2fa1388bb5b489ee8ee5f7291d692638ea5f67982d968366bef9f"}, + {file = "MarkupSafe-2.0.1-cp36-cp36m-win32.whl", hash = "sha256:6c4ca60fa24e85fe25b912b01e62cb969d69a23a5d5867682dd3e80b5b02581d"}, + {file = "MarkupSafe-2.0.1-cp36-cp36m-win_amd64.whl", hash = "sha256:b2f4bf27480f5e5e8ce285a8c8fd176c0b03e93dcc6646477d4630e83440c6a9"}, + {file = "MarkupSafe-2.0.1-cp37-cp37m-macosx_10_9_x86_64.whl", hash = "sha256:0717a7390a68be14b8c793ba258e075c6f4ca819f15edfc2a3a027c823718567"}, + {file = "MarkupSafe-2.0.1-cp37-cp37m-manylinux1_i686.whl", hash = "sha256:6557b31b5e2c9ddf0de32a691f2312a32f77cd7681d8af66c2692efdbef84c18"}, + {file = "MarkupSafe-2.0.1-cp37-cp37m-manylinux1_x86_64.whl", hash = "sha256:49e3ceeabbfb9d66c3aef5af3a60cc43b85c33df25ce03d0031a608b0a8b2e3f"}, + {file = "MarkupSafe-2.0.1-cp37-cp37m-manylinux2010_i686.whl", hash = "sha256:d7f9850398e85aba693bb640262d3611788b1f29a79f0c93c565694658f4071f"}, + {file = "MarkupSafe-2.0.1-cp37-cp37m-manylinux2010_x86_64.whl", hash = "sha256:6a7fae0dd14cf60ad5ff42baa2e95727c3d81ded453457771d02b7d2b3f9c0c2"}, + {file = "MarkupSafe-2.0.1-cp37-cp37m-manylinux2014_aarch64.whl", hash = "sha256:b7f2d075102dc8c794cbde1947378051c4e5180d52d276987b8d28a3bd58c17d"}, + {file = "MarkupSafe-2.0.1-cp37-cp37m-win32.whl", hash = "sha256:a30e67a65b53ea0a5e62fe23682cfe22712e01f453b95233b25502f7c61cb415"}, + {file = "MarkupSafe-2.0.1-cp37-cp37m-win_amd64.whl", hash = "sha256:611d1ad9a4288cf3e3c16014564df047fe08410e628f89805e475368bd304914"}, + {file = "MarkupSafe-2.0.1-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:be98f628055368795d818ebf93da628541e10b75b41c559fdf36d104c5787066"}, + {file = "MarkupSafe-2.0.1-cp38-cp38-manylinux1_i686.whl", hash = "sha256:1d609f577dc6e1aa17d746f8bd3c31aa4d258f4070d61b2aa5c4166c1539de35"}, + {file = "MarkupSafe-2.0.1-cp38-cp38-manylinux1_x86_64.whl", hash = "sha256:7d91275b0245b1da4d4cfa07e0faedd5b0812efc15b702576d103293e252af1b"}, + {file = "MarkupSafe-2.0.1-cp38-cp38-manylinux2010_i686.whl", hash = "sha256:01a9b8ea66f1658938f65b93a85ebe8bc016e6769611be228d797c9d998dd298"}, + {file = "MarkupSafe-2.0.1-cp38-cp38-manylinux2010_x86_64.whl", hash = "sha256:47ab1e7b91c098ab893b828deafa1203de86d0bc6ab587b160f78fe6c4011f75"}, + {file = "MarkupSafe-2.0.1-cp38-cp38-manylinux2014_aarch64.whl", hash = "sha256:97383d78eb34da7e1fa37dd273c20ad4320929af65d156e35a5e2d89566d9dfb"}, + {file = "MarkupSafe-2.0.1-cp38-cp38-win32.whl", hash = "sha256:023cb26ec21ece8dc3907c0e8320058b2e0cb3c55cf9564da612bc325bed5e64"}, + {file = "MarkupSafe-2.0.1-cp38-cp38-win_amd64.whl", hash = "sha256:984d76483eb32f1bcb536dc27e4ad56bba4baa70be32fa87152832cdd9db0833"}, + {file = "MarkupSafe-2.0.1-cp39-cp39-macosx_10_9_universal2.whl", hash = "sha256:2ef54abee730b502252bcdf31b10dacb0a416229b72c18b19e24a4509f273d26"}, + {file = "MarkupSafe-2.0.1-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:3c112550557578c26af18a1ccc9e090bfe03832ae994343cfdacd287db6a6ae7"}, + {file = "MarkupSafe-2.0.1-cp39-cp39-manylinux1_i686.whl", hash = "sha256:53edb4da6925ad13c07b6d26c2a852bd81e364f95301c66e930ab2aef5b5ddd8"}, + {file = "MarkupSafe-2.0.1-cp39-cp39-manylinux1_x86_64.whl", hash = "sha256:f5653a225f31e113b152e56f154ccbe59eeb1c7487b39b9d9f9cdb58e6c79dc5"}, + {file = "MarkupSafe-2.0.1-cp39-cp39-manylinux2010_i686.whl", hash = "sha256:4efca8f86c54b22348a5467704e3fec767b2db12fc39c6d963168ab1d3fc9135"}, + {file = "MarkupSafe-2.0.1-cp39-cp39-manylinux2010_x86_64.whl", hash = "sha256:ab3ef638ace319fa26553db0624c4699e31a28bb2a835c5faca8f8acf6a5a902"}, + {file = "MarkupSafe-2.0.1-cp39-cp39-manylinux2014_aarch64.whl", hash = "sha256:f8ba0e8349a38d3001fae7eadded3f6606f0da5d748ee53cc1dab1d6527b9509"}, + {file = "MarkupSafe-2.0.1-cp39-cp39-win32.whl", hash = "sha256:10f82115e21dc0dfec9ab5c0223652f7197feb168c940f3ef61563fc2d6beb74"}, + {file = "MarkupSafe-2.0.1-cp39-cp39-win_amd64.whl", hash = "sha256:693ce3f9e70a6cf7d2fb9e6c9d8b204b6b39897a2c4a1aa65728d5ac97dcc1d8"}, + {file = "MarkupSafe-2.0.1.tar.gz", hash = "sha256:594c67807fb16238b30c44bdf74f36c02cdf22d1c8cda91ef8a0ed8dabf5620a"}, +] mccabe = [ {file = "mccabe-0.6.1-py2.py3-none-any.whl", hash = "sha256:ab8a6258860da4b6677da4bd2fe5dc2c659cff31b3ee4f7f5d64e79735b80d42"}, {file = "mccabe-0.6.1.tar.gz", hash = "sha256:dd8d182285a0fe56bace7f45b5e7d1a6ebcbf524e8f3bd87eb0f125271b8831f"}, ] +mistune = [ + {file = "mistune-0.8.4-py2.py3-none-any.whl", hash = "sha256:88a1051873018da288eee8538d476dffe1262495144b33ecb586c4ab266bb8d4"}, + {file = "mistune-0.8.4.tar.gz", hash = "sha256:59a3429db53c50b5c6bcc8a07f8848cb00d7dc8bdb431a4ab41920d201d4756e"}, +] mypy = [ {file = "mypy-0.782-cp35-cp35m-macosx_10_6_x86_64.whl", hash = "sha256:2c6cde8aa3426c1682d35190b59b71f661237d74b053822ea3d748e2c9578a7c"}, {file = "mypy-0.782-cp35-cp35m-manylinux1_x86_64.whl", hash = "sha256:9c7a9a7ceb2871ba4bac1cf7217a7dd9ccd44c27c2950edbc6dc08530f32ad4e"}, @@ -734,6 +1076,10 @@ pyflakes = [ {file = "pyflakes-2.2.0-py2.py3-none-any.whl", hash = "sha256:0d94e0e05a19e57a99444b6ddcf9a6eb2e5c68d3ca1e98e90707af8152c90a92"}, {file = "pyflakes-2.2.0.tar.gz", hash = "sha256:35b2d75ee967ea93b55750aa9edbbf72813e06a66ba54438df2cfac9e3c27fc8"}, ] +pygments = [ + {file = "Pygments-2.9.0-py3-none-any.whl", hash = "sha256:d66e804411278594d764fc69ec36ec13d9ae9147193a1740cd34d272ca383b8e"}, + {file = "Pygments-2.9.0.tar.gz", hash = "sha256:a18f47b506a429f6f4b9df81bb02beab9ca21d0a5fee38ed15aef65f0545519f"}, +] pylint = [ {file = "pylint-2.6.0-py3-none-any.whl", hash = "sha256:bfe68f020f8a0fece830a22dd4d5dddb4ecc6137db04face4c3420a46a52239f"}, {file = "pylint-2.6.0.tar.gz", hash = "sha256:bb4a908c9dadbc3aac18860550e870f58e1a02c9f2c204fdf5693d73be061210"}, @@ -754,6 +1100,10 @@ pytest-structlog = [ {file = "pytest-structlog-0.3.tar.gz", hash = "sha256:be01025a712f03e9e2ede3bfbd9bce7ce79d4b7449d426fc603bebfcb0b7e860"}, {file = "pytest_structlog-0.3-py2.py3-none-any.whl", hash = "sha256:c07ab9c89ee942ca5776ac81c746387dcb26d52c53466ee850daab67bb5b0281"}, ] +pytz = [ + {file = "pytz-2021.1-py2.py3-none-any.whl", hash = "sha256:eb10ce3e7736052ed3623d49975ce333bcd712c7bb19a58b9e2089d4057d0798"}, + {file = "pytz-2021.1.tar.gz", hash = "sha256:83a4a90894bf38e243cf052c8b58f381bfe9a7a483f6a9cab140bc7f702ac4da"}, +] pyyaml = [ {file = "PyYAML-5.3.1-cp27-cp27m-win32.whl", hash = "sha256:74809a57b329d6cc0fdccee6318f44b9b8649961fa73144a98735b0aaf029f1f"}, {file = "PyYAML-5.3.1-cp27-cp27m-win_amd64.whl", hash = "sha256:240097ff019d7c70a4922b6869d8a86407758333f02203e0fc6ff79c5dcede76"}, @@ -765,6 +1115,8 @@ pyyaml = [ {file = "PyYAML-5.3.1-cp37-cp37m-win_amd64.whl", hash = "sha256:73f099454b799e05e5ab51423c7bcf361c58d3206fa7b0d555426b1f4d9a3eaf"}, {file = "PyYAML-5.3.1-cp38-cp38-win32.whl", hash = "sha256:06a0d7ba600ce0b2d2fe2e78453a470b5a6e000a985dd4a4e54e436cc36b0e97"}, {file = "PyYAML-5.3.1-cp38-cp38-win_amd64.whl", hash = "sha256:95f71d2af0ff4227885f7a6605c37fd53d3a106fcab511b8860ecca9fcf400ee"}, + {file = "PyYAML-5.3.1-cp39-cp39-win32.whl", hash = "sha256:ad9c67312c84def58f3c04504727ca879cb0013b2517c85a9a253f0cb6380c0a"}, + {file = "PyYAML-5.3.1-cp39-cp39-win_amd64.whl", hash = "sha256:6034f55dab5fea9e53f436aa68fa3ace2634918e8b5994d82f3621c04ff5ed2e"}, {file = "PyYAML-5.3.1.tar.gz", hash = "sha256:b8eac752c5e14d3eca0e6dd9199cd627518cb5ec06add0de9d32baeee6fe645d"}, ] regex = [ @@ -810,6 +1162,10 @@ regex = [ {file = "regex-2020.11.13-cp39-cp39-win_amd64.whl", hash = "sha256:a15f64ae3a027b64496a71ab1f722355e570c3fac5ba2801cafce846bf5af01d"}, {file = "regex-2020.11.13.tar.gz", hash = "sha256:83d6b356e116ca119db8e7c6fc2983289d87b27b3fac238cfe5dca529d884562"}, ] +requests = [ + {file = "requests-2.25.1-py2.py3-none-any.whl", hash = "sha256:c210084e36a42ae6b9219e00e48287def368a26d03a048ddad7bfee44f75871e"}, + {file = "requests-2.25.1.tar.gz", hash = "sha256:27973dd4a904a4f13b263a19c866c13b92a39ed1c964655f025f3f8d3d75b804"}, +] six = [ {file = "six-1.15.0-py2.py3-none-any.whl", hash = "sha256:8b74bedcbbbaca38ff6d7491d76f2b06b3592611af620f8426e82dddb04a5ced"}, {file = "six-1.15.0.tar.gz", hash = "sha256:30639c035cdb23534cd4aa2dd52c3bf48f06e5f4a941509c8bafd8ce11080259"}, @@ -822,6 +1178,38 @@ snowballstemmer = [ {file = "snowballstemmer-2.0.0-py2.py3-none-any.whl", hash = "sha256:209f257d7533fdb3cb73bdbd24f436239ca3b2fa67d56f6ff88e86be08cc5ef0"}, {file = "snowballstemmer-2.0.0.tar.gz", hash = "sha256:df3bac3df4c2c01363f3dd2cfa78cce2840a79b9f1c2d2de9ce8d31683992f52"}, ] +sphinx = [ + {file = "Sphinx-4.0.2-py3-none-any.whl", hash = "sha256:d1cb10bee9c4231f1700ec2e24a91be3f3a3aba066ea4ca9f3bbe47e59d5a1d4"}, + {file = "Sphinx-4.0.2.tar.gz", hash = "sha256:b5c2ae4120bf00c799ba9b3699bc895816d272d120080fbc967292f29b52b48c"}, +] +sphinx-rtd-theme = [ + {file = "sphinx_rtd_theme-0.5.2-py2.py3-none-any.whl", hash = "sha256:4a05bdbe8b1446d77a01e20a23ebc6777c74f43237035e76be89699308987d6f"}, + {file = "sphinx_rtd_theme-0.5.2.tar.gz", hash = "sha256:32bd3b5d13dc8186d7a42fc816a23d32e83a4827d7d9882948e7b837c232da5a"}, +] +sphinxcontrib-applehelp = [ + {file = "sphinxcontrib-applehelp-1.0.2.tar.gz", hash = "sha256:a072735ec80e7675e3f432fcae8610ecf509c5f1869d17e2eecff44389cdbc58"}, + {file = "sphinxcontrib_applehelp-1.0.2-py2.py3-none-any.whl", hash = "sha256:806111e5e962be97c29ec4c1e7fe277bfd19e9652fb1a4392105b43e01af885a"}, +] +sphinxcontrib-devhelp = [ + {file = "sphinxcontrib-devhelp-1.0.2.tar.gz", hash = "sha256:ff7f1afa7b9642e7060379360a67e9c41e8f3121f2ce9164266f61b9f4b338e4"}, + {file = "sphinxcontrib_devhelp-1.0.2-py2.py3-none-any.whl", hash = "sha256:8165223f9a335cc1af7ffe1ed31d2871f325254c0423bc0c4c7cd1c1e4734a2e"}, +] +sphinxcontrib-htmlhelp = [ + {file = "sphinxcontrib-htmlhelp-2.0.0.tar.gz", hash = "sha256:f5f8bb2d0d629f398bf47d0d69c07bc13b65f75a81ad9e2f71a63d4b7a2f6db2"}, + {file = "sphinxcontrib_htmlhelp-2.0.0-py2.py3-none-any.whl", hash = "sha256:d412243dfb797ae3ec2b59eca0e52dac12e75a241bf0e4eb861e450d06c6ed07"}, +] +sphinxcontrib-jsmath = [ + {file = "sphinxcontrib-jsmath-1.0.1.tar.gz", hash = "sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8"}, + {file = "sphinxcontrib_jsmath-1.0.1-py2.py3-none-any.whl", hash = "sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178"}, +] +sphinxcontrib-qthelp = [ + {file = "sphinxcontrib-qthelp-1.0.3.tar.gz", hash = "sha256:4c33767ee058b70dba89a6fc5c1892c0d57a54be67ddd3e7875a18d14cba5a72"}, + {file = "sphinxcontrib_qthelp-1.0.3-py2.py3-none-any.whl", hash = "sha256:bd9fc24bcb748a8d51fd4ecaade681350aa63009a347a8c14e637895444dfab6"}, +] +sphinxcontrib-serializinghtml = [ + {file = "sphinxcontrib-serializinghtml-1.1.5.tar.gz", hash = "sha256:aa5f6de5dfdf809ef505c4895e51ef5c9eac17d0f287933eb49ec495280b6952"}, + {file = "sphinxcontrib_serializinghtml-1.1.5-py2.py3-none-any.whl", hash = "sha256:352a9a00ae864471d3a7ead8d7d79f5fc0b57e8b3f95e9867eb9eb28999b92fd"}, +] stevedore = [ {file = "stevedore-3.3.0-py3-none-any.whl", hash = "sha256:50d7b78fbaf0d04cd62411188fa7eedcb03eb7f4c4b37005615ceebe582aa82a"}, {file = "stevedore-3.3.0.tar.gz", hash = "sha256:3a5bbd0652bf552748871eaa73a4a8dc2899786bc497a2aa1fcb4dcdb0debeee"}, @@ -842,19 +1230,28 @@ typed-ast = [ {file = "typed_ast-1.4.1-cp36-cp36m-macosx_10_9_x86_64.whl", hash = "sha256:269151951236b0f9a6f04015a9004084a5ab0d5f19b57de779f908621e7d8b75"}, {file = "typed_ast-1.4.1-cp36-cp36m-manylinux1_i686.whl", hash = "sha256:24995c843eb0ad11a4527b026b4dde3da70e1f2d8806c99b7b4a7cf491612652"}, {file = "typed_ast-1.4.1-cp36-cp36m-manylinux1_x86_64.whl", hash = "sha256:fe460b922ec15dd205595c9b5b99e2f056fd98ae8f9f56b888e7a17dc2b757e7"}, + {file = "typed_ast-1.4.1-cp36-cp36m-manylinux2014_aarch64.whl", hash = "sha256:fcf135e17cc74dbfbc05894ebca928ffeb23d9790b3167a674921db19082401f"}, {file = "typed_ast-1.4.1-cp36-cp36m-win32.whl", hash = "sha256:4e3e5da80ccbebfff202a67bf900d081906c358ccc3d5e3c8aea42fdfdfd51c1"}, {file = "typed_ast-1.4.1-cp36-cp36m-win_amd64.whl", hash = "sha256:249862707802d40f7f29f6e1aad8d84b5aa9e44552d2cc17384b209f091276aa"}, {file = "typed_ast-1.4.1-cp37-cp37m-macosx_10_9_x86_64.whl", hash = "sha256:8ce678dbaf790dbdb3eba24056d5364fb45944f33553dd5869b7580cdbb83614"}, {file = "typed_ast-1.4.1-cp37-cp37m-manylinux1_i686.whl", hash = "sha256:c9e348e02e4d2b4a8b2eedb48210430658df6951fa484e59de33ff773fbd4b41"}, {file = "typed_ast-1.4.1-cp37-cp37m-manylinux1_x86_64.whl", hash = "sha256:bcd3b13b56ea479b3650b82cabd6b5343a625b0ced5429e4ccad28a8973f301b"}, + {file = "typed_ast-1.4.1-cp37-cp37m-manylinux2014_aarch64.whl", hash = "sha256:f208eb7aff048f6bea9586e61af041ddf7f9ade7caed625742af423f6bae3298"}, {file = "typed_ast-1.4.1-cp37-cp37m-win32.whl", hash = "sha256:d5d33e9e7af3b34a40dc05f498939f0ebf187f07c385fd58d591c533ad8562fe"}, {file = "typed_ast-1.4.1-cp37-cp37m-win_amd64.whl", hash = "sha256:0666aa36131496aed8f7be0410ff974562ab7eeac11ef351def9ea6fa28f6355"}, {file = "typed_ast-1.4.1-cp38-cp38-macosx_10_15_x86_64.whl", hash = "sha256:d205b1b46085271b4e15f670058ce182bd1199e56b317bf2ec004b6a44f911f6"}, {file = "typed_ast-1.4.1-cp38-cp38-manylinux1_i686.whl", hash = "sha256:6daac9731f172c2a22ade6ed0c00197ee7cc1221aa84cfdf9c31defeb059a907"}, {file = "typed_ast-1.4.1-cp38-cp38-manylinux1_x86_64.whl", hash = "sha256:498b0f36cc7054c1fead3d7fc59d2150f4d5c6c56ba7fb150c013fbc683a8d2d"}, + {file = "typed_ast-1.4.1-cp38-cp38-manylinux2014_aarch64.whl", hash = "sha256:7e4c9d7658aaa1fc80018593abdf8598bf91325af6af5cce4ce7c73bc45ea53d"}, {file = "typed_ast-1.4.1-cp38-cp38-win32.whl", hash = "sha256:715ff2f2df46121071622063fc7543d9b1fd19ebfc4f5c8895af64a77a8c852c"}, {file = "typed_ast-1.4.1-cp38-cp38-win_amd64.whl", hash = "sha256:fc0fea399acb12edbf8a628ba8d2312f583bdbdb3335635db062fa98cf71fca4"}, {file = "typed_ast-1.4.1-cp39-cp39-macosx_10_15_x86_64.whl", hash = "sha256:d43943ef777f9a1c42bf4e552ba23ac77a6351de620aa9acf64ad54933ad4d34"}, + {file = "typed_ast-1.4.1-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:92c325624e304ebf0e025d1224b77dd4e6393f18aab8d829b5b7e04afe9b7a2c"}, + {file = "typed_ast-1.4.1-cp39-cp39-manylinux1_i686.whl", hash = "sha256:d648b8e3bf2fe648745c8ffcee3db3ff903d0817a01a12dd6a6ea7a8f4889072"}, + {file = "typed_ast-1.4.1-cp39-cp39-manylinux1_x86_64.whl", hash = "sha256:fac11badff8313e23717f3dada86a15389d0708275bddf766cca67a84ead3e91"}, + {file = "typed_ast-1.4.1-cp39-cp39-manylinux2014_aarch64.whl", hash = "sha256:0d8110d78a5736e16e26213114a38ca35cb15b6515d535413b090bd50951556d"}, + {file = "typed_ast-1.4.1-cp39-cp39-win32.whl", hash = "sha256:b52ccf7cfe4ce2a1064b18594381bccf4179c2ecf7f513134ec2f993dd4ab395"}, + {file = "typed_ast-1.4.1-cp39-cp39-win_amd64.whl", hash = "sha256:3742b32cf1c6ef124d57f95be609c473d7ec4c14d0090e5a5e05a15269fb4d0c"}, {file = "typed_ast-1.4.1.tar.gz", hash = "sha256:8c8aaad94455178e3187ab22c8b01a3837f8ee50e09cf31f1ba129eb293ec30b"}, ] typing-extensions = [ @@ -862,6 +1259,10 @@ typing-extensions = [ {file = "typing_extensions-3.7.4.3-py3-none-any.whl", hash = "sha256:7cb407020f00f7bfc3cb3e7881628838e69d8f3fcab2f64742a5e76b2f841918"}, {file = "typing_extensions-3.7.4.3.tar.gz", hash = "sha256:99d4073b617d30288f569d3f13d2bd7548c3a7e4c8de87db09a9d29bb3a4a60c"}, ] +urllib3 = [ + {file = "urllib3-1.26.5-py2.py3-none-any.whl", hash = "sha256:753a0374df26658f99d826cfe40394a686d05985786d946fbe4165b5148f5a7c"}, + {file = "urllib3-1.26.5.tar.gz", hash = "sha256:a7acd0977125325f516bda9735fa7142b909a8d01e8b2e4c8108d0984e6e0098"}, +] wrapt = [ {file = "wrapt-1.12.1.tar.gz", hash = "sha256:b62ffa81fb85f4332a4f609cab4ac40709470da05643a082ec1eb88e6d9b97d7"}, ] diff --git a/pyproject.toml b/pyproject.toml index ed06dfe8..426313a8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -37,6 +37,9 @@ mypy = "^0.782" pytest-cov = "^2.10.1" pytest-structlog = "^0.3" coverage = {extras = ["toml"], version = "^5.3"} +Sphinx = "^4.0.2" +m2r2 = "^0.2.7" +sphinx-rtd-theme = "^0.5.2" [tool.black] line-length = 120 From 1927dd889780ad648a747ae7e5f3e826580a92ae Mon Sep 17 00:00:00 2001 From: Josh Silvas Date: Mon, 21 Jun 2021 12:01:07 -0500 Subject: [PATCH 02/22] Adds RTD requirements --- .readthedocs.yml | 4 ++++ docs/requirements.txt | 4 ++++ 2 files changed, 8 insertions(+) create mode 100644 docs/requirements.txt diff --git a/.readthedocs.yml b/.readthedocs.yml index 70f6983d..492d9c46 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -6,3 +6,7 @@ sphinx: configuration: "docs/source/conf.py" fail_on_warning: false +python: + version: 3.7 + install: + - requirements: "docs/requirements.txt" diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..7b89a7ac --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,4 @@ +m2r2==0.2.7 +Sphinx +toml +sphinx-rtd-theme \ No newline at end of file From f5f935722a7a8fce13cfd824e56a63aad0657e5b Mon Sep 17 00:00:00 2001 From: Josh Silvas Date: Mon, 21 Jun 2021 12:49:29 -0500 Subject: [PATCH 03/22] Adds sphinx callback for RTD to run apidoc generator. --- docs/source/conf.py | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index a24979e7..1b914c37 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -13,6 +13,8 @@ import os import sys +from sphinx.ext.apidoc import main + try: import toml except ImportError: @@ -21,7 +23,8 @@ # -- Variable setup -------------------------------------------------------------- -PYPROJECT_CONFIG = toml.load(f"{os.path.dirname(os.path.dirname(os.getcwd()))}/pyproject.toml") +CURR_DIR = os.path.dirname(os.path.dirname(os.getcwd())) +PYPROJECT_CONFIG = toml.load(f"{CURR_DIR}/pyproject.toml") TOOL_CONFIG = PYPROJECT_CONFIG["tool"]["poetry"] # -- Project information ----------------------------------------------------- @@ -83,5 +86,13 @@ def remove_module_docstring(app, what, name, obj, options, lines): del lines[1:] +def run_apidoc(_): + """Adds the sphinx-apidoc command as a callback during the build process.""" + src_dir = f"{CURR_DIR}/docs/source" + main(["-MTf", "-t", f"{src_dir}/template/api", "-o", f"{src_dir}/api", 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) From 02e60f48ad14b76cff6bf3658c2c8a12a8be3b60 Mon Sep 17 00:00:00 2001 From: Josh Silvas Date: Mon, 21 Jun 2021 15:23:45 -0500 Subject: [PATCH 04/22] Update getting_started/index.rst line lengh --- docs/source/conf.py | 5 +++-- docs/source/getting_started/index.rst | 4 ++-- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 1b914c37..722d861c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -88,8 +88,9 @@ def remove_module_docstring(app, what, name, obj, options, lines): def run_apidoc(_): """Adds the sphinx-apidoc command as a callback during the build process.""" - src_dir = f"{CURR_DIR}/docs/source" - main(["-MTf", "-t", f"{src_dir}/template/api", "-o", f"{src_dir}/api", TOOL_CONFIG["name"]]) + cur_dir = os.path.abspath(os.path.dirname(__file__)) + print(cur_dir) + main([TOOL_CONFIG["name"], "-MTf", "-t", f"{cur_dir}/template/api", "-o", f"{cur_dir}/api"]) def setup(app): diff --git a/docs/source/getting_started/index.rst b/docs/source/getting_started/index.rst index 35b05952..db41d096 100644 --- a/docs/source/getting_started/index.rst +++ b/docs/source/getting_started/index.rst @@ -1,6 +1,6 @@ -############ +############### Getting Started -############ +############### .. mdinclude:: ../../../README.md :start-line: 28 From 888c12ee4fdaf07487ec1cd54cbe68da507fb4cb Mon Sep 17 00:00:00 2001 From: Josh Silvas Date: Mon, 21 Jun 2021 16:04:20 -0500 Subject: [PATCH 05/22] Updates docs/conf.py with correct root directory. --- docs/source/conf.py | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 722d861c..aac6a956 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -10,9 +10,9 @@ # 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. # -import os import sys +from pathlib import Path from sphinx.ext.apidoc import main try: @@ -23,8 +23,9 @@ # -- Variable setup -------------------------------------------------------------- -CURR_DIR = os.path.dirname(os.path.dirname(os.getcwd())) -PYPROJECT_CONFIG = toml.load(f"{CURR_DIR}/pyproject.toml") +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"] # -- Project information ----------------------------------------------------- @@ -88,9 +89,7 @@ def remove_module_docstring(app, what, name, obj, options, lines): def run_apidoc(_): """Adds the sphinx-apidoc command as a callback during the build process.""" - cur_dir = os.path.abspath(os.path.dirname(__file__)) - print(cur_dir) - main([TOOL_CONFIG["name"], "-MTf", "-t", f"{cur_dir}/template/api", "-o", f"{cur_dir}/api"]) + main(["-MTf", "-t", f"{CURR_DIR}/template/api", "-o", f"{CURR_DIR}/api", f"{ROOT_DIR}/{TOOL_CONFIG['name']}"]) def setup(app): From 3ec327e700a87c858574a57870b5e32b3fafef50 Mon Sep 17 00:00:00 2001 From: Josh Silvas Date: Mon, 21 Jun 2021 16:11:15 -0500 Subject: [PATCH 06/22] Adds import of diffsync library --- docs/source/conf.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index aac6a956..411e64cc 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -10,6 +10,7 @@ # 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. # +import os import sys from pathlib import Path @@ -20,7 +21,6 @@ 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 @@ -28,6 +28,10 @@ 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(f"{ROOT_DIR}/{TOOL_CONFIG['name']}/")) + # -- Project information ----------------------------------------------------- project = TOOL_CONFIG["name"] From 66919a9b3d8e89782ded001d20ebf8dd3af0c23b Mon Sep 17 00:00:00 2001 From: Josh Silvas Date: Mon, 21 Jun 2021 16:17:23 -0500 Subject: [PATCH 07/22] Updates path imports --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 411e64cc..afc121b9 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -30,7 +30,7 @@ # 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(f"{ROOT_DIR}/{TOOL_CONFIG['name']}/")) +sys.path.insert(0, os.path.abspath("../..")) # -- Project information ----------------------------------------------------- From 8bf41b3600bfeb506a6316e8713da2eb96e8aaae Mon Sep 17 00:00:00 2001 From: Josh Silvas Date: Mon, 21 Jun 2021 16:35:40 -0500 Subject: [PATCH 08/22] Updates doc requirements.txt --- docs/requirements.txt | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index 7b89a7ac..21bc0499 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,8 @@ m2r2==0.2.7 Sphinx toml -sphinx-rtd-theme \ No newline at end of file +sphinx-rtd-theme +pydantic +structlog +colorama +dataclasses \ No newline at end of file From 77eb691cb903a96f3c8aabc66888c76bdba83b45 Mon Sep 17 00:00:00 2001 From: Josh Silvas Date: Mon, 21 Jun 2021 20:06:17 -0500 Subject: [PATCH 09/22] Add invoke commands for documentation. --- tasks.py | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/tasks.py b/tasks.py index fb3a98c2..59afed01 100644 --- a/tasks.py +++ b/tasks.py @@ -298,3 +298,44 @@ def tests(context, name=NAME, image_ver=IMAGE_VER, local=INVOKE_LOCAL): pytest(context, name, image_ver, local) print("All tests have passed!") + + +@task +def html(context, sourcedir="docs/source", builddir="docs/build"): + """Creates html docs using sphinx-build command. + + Args: + context (obj): Used to run specific commands + sourcedir (str, optional): Source directory for sphinx to use. Defaults to "source". + builddir (str, optional): Output directory for sphinx to use. Defaults to "build". + """ + print("Building html documentation...") + clean_docs(context, builddir) + command = f"sphinx-build {sourcedir} {builddir}" + context.run(command) + + +@task +def api_doc(context, sourcedir="diffsync", output="docs/source/api"): + """Creates api docs using sphinx-apidoc command. + + Args: + context (obj): Used to run specific commands + sourcedir (str, optional): Source directory for sphinx-apidoc to use. Defaults to "diffsync". + output (str, optional): Output dir for sphinx-apidoc to place rendered files. Defaults to "docs/source/api". + """ + print("Building api documentation...") + command = f"sphinx-apidoc -MTf -t docs/source/template/api -o {output} {sourcedir}" + context.run(command) + + +@task +def clean_docs(context, builddir="docs/build"): + """Removes the build directory and all of its contents. + + Args: + context (obj): Used to run specific commands + builddir (str, optional): Directory to be removed. Defaults to "build". + """ + print(f"Removing everything under {builddir} directory...") + context.run("rm -rf " + builddir) \ No newline at end of file From ef16caeb7e8ab287b0a797230af887df2b9bff46 Mon Sep 17 00:00:00 2001 From: Josh Silvas Date: Mon, 21 Jun 2021 20:32:28 -0500 Subject: [PATCH 10/22] Adds small changes for tests. --- docs/source/conf.py | 31 ++++++++++++++----------------- tasks.py | 2 +- 2 files changed, 15 insertions(+), 18 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index afc121b9..ed663651 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,15 +1,16 @@ -# 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 +"""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 @@ -36,7 +37,7 @@ project = TOOL_CONFIG["name"] copyright = f"2021, {','.join(TOOL_CONFIG['authors'])}" -author = ','.join(TOOL_CONFIG['authors']) +author = ",".join(TOOL_CONFIG["authors"]) # The full version, including alpha/beta/rc tags release = TOOL_CONFIG["version"] @@ -47,11 +48,7 @@ # 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" -] +extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon", "m2r2"] autodoc_default_options = { "members": True, @@ -62,12 +59,12 @@ # Add any paths that contain templates here, relative to this directory. -templates_path = ['templates'] +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'] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] # -- Options for HTML output ------------------------------------------------- @@ -75,16 +72,16 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'sphinx_rtd_theme' +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'] +html_static_path = ["static"] def remove_module_docstring(app, what, name, obj, options, lines): - """Removes copyright information at the top of each module to prevent unneeded reference in the API documentation""" + """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. diff --git a/tasks.py b/tasks.py index 59afed01..c042640a 100644 --- a/tasks.py +++ b/tasks.py @@ -338,4 +338,4 @@ def clean_docs(context, builddir="docs/build"): builddir (str, optional): Directory to be removed. Defaults to "build". """ print(f"Removing everything under {builddir} directory...") - context.run("rm -rf " + builddir) \ No newline at end of file + context.run("rm -rf " + builddir) From dc9f57b99f2bd6473c1111da6b46bbdea5650dc3 Mon Sep 17 00:00:00 2001 From: Josh Silvas Date: Mon, 21 Jun 2021 20:57:11 -0500 Subject: [PATCH 11/22] Move doc requirements into pyproject.toml --- .readthedocs.yml | 5 ++++- docs/requirements.txt | 8 -------- pyproject.toml | 16 +++++++++++++++- 3 files changed, 19 insertions(+), 10 deletions(-) delete mode 100644 docs/requirements.txt diff --git a/.readthedocs.yml b/.readthedocs.yml index 492d9c46..1238cd94 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -9,4 +9,7 @@ sphinx: python: version: 3.7 install: - - requirements: "docs/requirements.txt" + - method: pip + path: . + extra_requirements: + - docs diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index 21bc0499..00000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,8 +0,0 @@ -m2r2==0.2.7 -Sphinx -toml -sphinx-rtd-theme -pydantic -structlog -colorama -dataclasses \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 426313a8..40abf027 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -19,7 +19,9 @@ python = "^3.6" pydantic = "^1.7.4,!=1.8,!=1.8.1" structlog = "^20.1.0" colorama = {version = "^0.4.3", optional = true} - +sphinx = {version = "^4.0.2", optional = true} +m2r2 = {version = "^0.2.7", optional = true} +sphinx-rtd-theme = {version = "^0.5.2", optional = true} # For Pydantic dataclasses = {version = "^0.7", python = "~3.6"} @@ -41,6 +43,18 @@ Sphinx = "^4.0.2" m2r2 = "^0.2.7" sphinx-rtd-theme = "^0.5.2" +[tool.poetry.extras] +docs = [ + "Sphinx", + "m2r2", + "toml", + "sphinx-rtd-theme", + "pydantic", + "structlog", + "colorama", + "dataclasses" +] + [tool.black] line-length = 120 include = '\.pyi?$' From 2691199ef1f201db85c28123d86d660c648e277a Mon Sep 17 00:00:00 2001 From: Josh Silvas Date: Mon, 21 Jun 2021 21:07:55 -0500 Subject: [PATCH 12/22] Adds toml to optional poetry install --- pyproject.toml | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 40abf027..df172330 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -19,11 +19,14 @@ python = "^3.6" pydantic = "^1.7.4,!=1.8,!=1.8.1" structlog = "^20.1.0" colorama = {version = "^0.4.3", optional = true} +# For Pydantic +dataclasses = {version = "^0.7", python = "~3.6"} + +# For RTD poetry integration sphinx = {version = "^4.0.2", optional = true} m2r2 = {version = "^0.2.7", optional = true} sphinx-rtd-theme = {version = "^0.5.2", optional = true} -# For Pydantic -dataclasses = {version = "^0.7", python = "~3.6"} +toml = {version = "^0.5.2", optional = true} [tool.poetry.dev-dependencies] pytest = "^6.1.0" @@ -45,7 +48,7 @@ sphinx-rtd-theme = "^0.5.2" [tool.poetry.extras] docs = [ - "Sphinx", + "sphinx", "m2r2", "toml", "sphinx-rtd-theme", From 1b7e07e17592cdd310e456afb69e987a99cd6f63 Mon Sep 17 00:00:00 2001 From: Josh Silvas Date: Mon, 21 Jun 2021 21:10:02 -0500 Subject: [PATCH 13/22] Updates toml version --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index df172330..9fc262a9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -26,7 +26,7 @@ dataclasses = {version = "^0.7", python = "~3.6"} sphinx = {version = "^4.0.2", optional = true} m2r2 = {version = "^0.2.7", optional = true} sphinx-rtd-theme = {version = "^0.5.2", optional = true} -toml = {version = "^0.5.2", optional = true} +toml = {version = "^0.10.2", optional = true} [tool.poetry.dev-dependencies] pytest = "^6.1.0" From 665dd0df76d7bcadd47c7948fccad5235f8c1e63 Mon Sep 17 00:00:00 2001 From: Josh Silvas Date: Mon, 21 Jun 2021 21:19:02 -0500 Subject: [PATCH 14/22] Update example titles. --- .readthedocs.yml | 6 +++--- .../examples/{example1.rst => 01-multiple-data-sources.rst} | 6 +++--- .../examples/{example2.rst => 02-callback-function.rst} | 6 +++--- docs/source/examples/index.rst | 4 ++-- 4 files changed, 11 insertions(+), 11 deletions(-) rename docs/source/examples/{example1.rst => 01-multiple-data-sources.rst} (50%) rename docs/source/examples/{example2.rst => 02-callback-function.rst} (60%) diff --git a/.readthedocs.yml b/.readthedocs.yml index 1238cd94..8d33d319 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -9,7 +9,7 @@ sphinx: python: version: 3.7 install: - - method: pip - path: . + - method: "pip" + path: "." extra_requirements: - - docs + - "docs" diff --git a/docs/source/examples/example1.rst b/docs/source/examples/01-multiple-data-sources.rst similarity index 50% rename from docs/source/examples/example1.rst rename to docs/source/examples/01-multiple-data-sources.rst index 2e9448b1..b0d68c2c 100644 --- a/docs/source/examples/example1.rst +++ b/docs/source/examples/01-multiple-data-sources.rst @@ -1,6 +1,6 @@ -********* -Example 1 -********* +**************************** +Using Multiple Data Sources +**************************** .. mdinclude:: ../../../examples/example1/README.md :start-line: 2 diff --git a/docs/source/examples/example2.rst b/docs/source/examples/02-callback-function.rst similarity index 60% rename from docs/source/examples/example2.rst rename to docs/source/examples/02-callback-function.rst index 92e263b9..5abce420 100644 --- a/docs/source/examples/example2.rst +++ b/docs/source/examples/02-callback-function.rst @@ -1,6 +1,6 @@ -********* -Example 2 -********* +****************** +Callback Function +****************** .. mdinclude:: ../../../examples/example2/README.md :start-line: 2 diff --git a/docs/source/examples/index.rst b/docs/source/examples/index.rst index 3dc70da2..60959e65 100644 --- a/docs/source/examples/index.rst +++ b/docs/source/examples/index.rst @@ -5,5 +5,5 @@ Examples .. toctree:: :maxdepth: 2 - example1 - example2 \ No newline at end of file + 01-multiple-data-sources + 02-callback-function \ No newline at end of file From 4edb6102f4f239fd79bca17b3080214dbf0ac1da Mon Sep 17 00:00:00 2001 From: Josh Silvas Date: Tue, 22 Jun 2021 07:57:22 -0500 Subject: [PATCH 15/22] Update documentation and homepage reference in pyproject.toml to point to the RTD site. --- pyproject.toml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 9fc262a9..2fdbc5fe 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -5,8 +5,9 @@ description = "Library to easily sync/diff/update 2 different data sources" authors = ["Network to Code, LLC "] license = "Apache-2.0" readme = "README.md" -homepage = "https://github.com/networktocode/diffsync" +homepage = "https://diffsync.readthedocs.io" repository = "https://github.com/networktocode/diffsync" +documentation = "https://diffsync.readthedocs.io" keywords = ["source-of-truth", "synchronization"] include = [ "CHANGELOG.md", From 63865d0fb234c3c37f921d63c9246c0a033baaff Mon Sep 17 00:00:00 2001 From: Josh Silvas Date: Tue, 22 Jun 2021 13:20:50 -0500 Subject: [PATCH 16/22] Update docs/source/conf.py Co-authored-by: Glenn Matthews --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index ed663651..ee551985 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -36,7 +36,7 @@ # -- Project information ----------------------------------------------------- project = TOOL_CONFIG["name"] -copyright = f"2021, {','.join(TOOL_CONFIG['authors'])}" +copyright = f"2020-2021, {','.join(TOOL_CONFIG['authors'])}" author = ",".join(TOOL_CONFIG["authors"]) # The full version, including alpha/beta/rc tags From 65e19ca27bbca6575c3697c50344c0084051e936 Mon Sep 17 00:00:00 2001 From: Josh Silvas Date: Wed, 23 Jun 2021 09:08:28 -0500 Subject: [PATCH 17/22] Convert from sphinx to mkdocs as per the standard. --- .readthedocs.yml | 5 +- README.md | 7 +- diffsync/__init__.py | 2 +- docs/api_reference/diff/index.md | 5 + docs/api_reference/diffsync.md | 4 + docs/api_reference/diffsyncmodel.md | 4 + docs/api_reference/enum/index.md | 5 + docs/api_reference/exceptions/index.md | 5 + docs/api_reference/helpers/index.md | 5 + docs/api_reference/logging/index.md | 5 + docs/api_reference/utils/index.md | 5 + docs/examples/example1.md | 4 + docs/examples/example2.md | 4 + docs/extra.css | 19 ++++ docs/getting_started.md | 8 ++ docs/index.md | 8 ++ docs/license.md | 5 + docs/source/api/diffsync.rst | 56 ----------- docs/source/conf.py | 99 ------------------- .../examples/01-multiple-data-sources.rst | 7 -- docs/source/examples/02-callback-function.rst | 7 -- docs/source/examples/index.rst | 9 -- docs/source/getting_started/index.rst | 7 -- docs/source/index.rst | 20 ---- docs/source/license/index.rst | 5 - docs/source/overview/index.rst | 7 -- docs/source/static/schema-page.css | 62 ------------ docs/source/static/theme_overrides.css | 13 --- docs/source/template/api/package.rst_t | 51 ---------- mkdocs.yml | 33 +++++++ pyproject.toml | 22 +---- tasks.py | 40 -------- 32 files changed, 129 insertions(+), 409 deletions(-) create mode 100644 docs/api_reference/diff/index.md create mode 100644 docs/api_reference/diffsync.md create mode 100644 docs/api_reference/diffsyncmodel.md create mode 100644 docs/api_reference/enum/index.md create mode 100644 docs/api_reference/exceptions/index.md create mode 100644 docs/api_reference/helpers/index.md create mode 100644 docs/api_reference/logging/index.md create mode 100644 docs/api_reference/utils/index.md create mode 100644 docs/examples/example1.md create mode 100644 docs/examples/example2.md create mode 100644 docs/extra.css create mode 100644 docs/getting_started.md create mode 100644 docs/index.md create mode 100644 docs/license.md delete mode 100644 docs/source/api/diffsync.rst delete mode 100644 docs/source/conf.py delete mode 100644 docs/source/examples/01-multiple-data-sources.rst delete mode 100644 docs/source/examples/02-callback-function.rst delete mode 100644 docs/source/examples/index.rst delete mode 100644 docs/source/getting_started/index.rst delete mode 100644 docs/source/index.rst delete mode 100644 docs/source/license/index.rst delete mode 100644 docs/source/overview/index.rst delete mode 100644 docs/source/static/schema-page.css delete mode 100644 docs/source/static/theme_overrides.css delete mode 100644 docs/source/template/api/package.rst_t create mode 100644 mkdocs.yml diff --git a/.readthedocs.yml b/.readthedocs.yml index 8d33d319..d19521d1 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -1,9 +1,8 @@ --- version: 2 -sphinx: - builder: "html" - configuration: "docs/source/conf.py" +mkdocs: + configuration: "mkdocs.yml" fail_on_warning: false python: diff --git a/README.md b/README.md index a66604f9..83d76aac 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ # DiffSync - + 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. - + # Getting started - + 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,3 +151,4 @@ 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) ``` + \ No newline at end of file diff --git a/diffsync/__init__.py b/diffsync/__init__.py index 44946067..15c3c01e 100644 --- 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 new file mode 100644 index 00000000..b12863e2 --- /dev/null +++ b/docs/api_reference/diff/index.md @@ -0,0 +1,5 @@ +# DiffSync.Diff + +::: diffsync.diff + + diff --git a/docs/api_reference/diffsync.md b/docs/api_reference/diffsync.md new file mode 100644 index 00000000..c98b639b --- /dev/null +++ b/docs/api_reference/diffsync.md @@ -0,0 +1,4 @@ +# DiffSync + +::: diffsync.DiffSync + diff --git a/docs/api_reference/diffsyncmodel.md b/docs/api_reference/diffsyncmodel.md new file mode 100644 index 00000000..198348bb --- /dev/null +++ b/docs/api_reference/diffsyncmodel.md @@ -0,0 +1,4 @@ +# DiffSync Model + +::: diffsync.DiffSyncModel + diff --git a/docs/api_reference/enum/index.md b/docs/api_reference/enum/index.md new file mode 100644 index 00000000..d2234ef5 --- /dev/null +++ b/docs/api_reference/enum/index.md @@ -0,0 +1,5 @@ +# DiffSync.Enum + +::: diffsync.enum + + diff --git a/docs/api_reference/exceptions/index.md b/docs/api_reference/exceptions/index.md new file mode 100644 index 00000000..416e33db --- /dev/null +++ b/docs/api_reference/exceptions/index.md @@ -0,0 +1,5 @@ +# DiffSync.Exceptions + +::: diffsync.exceptions + + diff --git a/docs/api_reference/helpers/index.md b/docs/api_reference/helpers/index.md new file mode 100644 index 00000000..abfe7455 --- /dev/null +++ b/docs/api_reference/helpers/index.md @@ -0,0 +1,5 @@ +# DiffSync.Helpers + +::: diffsync.helpers + + diff --git a/docs/api_reference/logging/index.md b/docs/api_reference/logging/index.md new file mode 100644 index 00000000..6256b77d --- /dev/null +++ b/docs/api_reference/logging/index.md @@ -0,0 +1,5 @@ +# DiffSync.Logging + +::: diffsync.logging + + diff --git a/docs/api_reference/utils/index.md b/docs/api_reference/utils/index.md new file mode 100644 index 00000000..afeb11cf --- /dev/null +++ b/docs/api_reference/utils/index.md @@ -0,0 +1,5 @@ +# DiffSync.Utils + +::: diffsync.utils + + diff --git a/docs/examples/example1.md b/docs/examples/example1.md new file mode 100644 index 00000000..6fb468f0 --- /dev/null +++ b/docs/examples/example1.md @@ -0,0 +1,4 @@ +{% + include-markdown "../../examples/example1/README.md" + heading-offset=1 +%} diff --git a/docs/examples/example2.md b/docs/examples/example2.md new file mode 100644 index 00000000..8eb0cff9 --- /dev/null +++ b/docs/examples/example2.md @@ -0,0 +1,4 @@ +{% + include-markdown "../../examples/example2/README.md" + heading-offset=1 +%} diff --git a/docs/extra.css b/docs/extra.css new file mode 100644 index 00000000..85d51a14 --- /dev/null +++ b/docs/extra.css @@ -0,0 +1,19 @@ +/* Images */ +img { + display: block; + margin-left: auto; + margin-right: auto; +} + +/* Tables */ +table { + margin-bottom: 24px; + width: 100%; +} +th { + background-color: #f0f0f0; + padding: 6px; +} +td { + padding: 6px; +} \ No newline at end of file diff --git a/docs/getting_started.md b/docs/getting_started.md new file mode 100644 index 00000000..649bff10 --- /dev/null +++ b/docs/getting_started.md @@ -0,0 +1,8 @@ +# Getting Started + +{% + include-markdown "../README.md" + start="" + end="" + heading-offset=1 +%} diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..abc9ffa4 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,8 @@ +# Welcome to the DiffSync Documentation! + +{% + include-markdown "../README.md" + start="" + end="" + heading-offset=1 +%} diff --git a/docs/license.md b/docs/license.md new file mode 100644 index 00000000..a6de5c6f --- /dev/null +++ b/docs/license.md @@ -0,0 +1,5 @@ +# License + +{% + include-markdown "../LICENSE" +%} diff --git a/docs/source/api/diffsync.rst b/docs/source/api/diffsync.rst deleted file mode 100644 index 473420e9..00000000 --- a/docs/source/api/diffsync.rst +++ /dev/null @@ -1,56 +0,0 @@ -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 deleted file mode 100644 index ee551985..00000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,99 +0,0 @@ -"""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 deleted file mode 100644 index b0d68c2c..00000000 --- a/docs/source/examples/01-multiple-data-sources.rst +++ /dev/null @@ -1,7 +0,0 @@ -**************************** -Using Multiple Data Sources -**************************** - -.. mdinclude:: ../../../examples/example1/README.md - :start-line: 2 - :end-line: 67 \ No newline at end of file diff --git a/docs/source/examples/02-callback-function.rst b/docs/source/examples/02-callback-function.rst deleted file mode 100644 index 5abce420..00000000 --- a/docs/source/examples/02-callback-function.rst +++ /dev/null @@ -1,7 +0,0 @@ -****************** -Callback Function -****************** - -.. mdinclude:: ../../../examples/example2/README.md - :start-line: 2 - :end-line: 44 \ No newline at end of file diff --git a/docs/source/examples/index.rst b/docs/source/examples/index.rst deleted file mode 100644 index 60959e65..00000000 --- a/docs/source/examples/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -############ -Examples -############ - -.. toctree:: - :maxdepth: 2 - - 01-multiple-data-sources - 02-callback-function \ No newline at end of file diff --git a/docs/source/getting_started/index.rst b/docs/source/getting_started/index.rst deleted file mode 100644 index db41d096..00000000 --- a/docs/source/getting_started/index.rst +++ /dev/null @@ -1,7 +0,0 @@ -############### -Getting Started -############### - -.. mdinclude:: ../../../README.md - :start-line: 28 - :end-line: 153 \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index 6d4d2c6d..00000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -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 deleted file mode 100644 index 112bcdff..00000000 --- a/docs/source/license/index.rst +++ /dev/null @@ -1,5 +0,0 @@ -############ -License -############ - -.. mdinclude:: ../../../LICENSE diff --git a/docs/source/overview/index.rst b/docs/source/overview/index.rst deleted file mode 100644 index 89a03204..00000000 --- a/docs/source/overview/index.rst +++ /dev/null @@ -1,7 +0,0 @@ -********* -Overview -********* - -.. mdinclude:: ../../../README.md - :start-line: 2 - :end-line: 25 \ No newline at end of file diff --git a/docs/source/static/schema-page.css b/docs/source/static/schema-page.css deleted file mode 100644 index 78f9f02c..00000000 --- a/docs/source/static/schema-page.css +++ /dev/null @@ -1,62 +0,0 @@ -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; -} \ No newline at end of file diff --git a/docs/source/static/theme_overrides.css b/docs/source/static/theme_overrides.css deleted file mode 100644 index 63ee6cc7..00000000 --- a/docs/source/static/theme_overrides.css +++ /dev/null @@ -1,13 +0,0 @@ -/* 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/package.rst_t b/docs/source/template/api/package.rst_t deleted file mode 100644 index 621e6ea4..00000000 --- a/docs/source/template/api/package.rst_t +++ /dev/null @@ -1,51 +0,0 @@ -{%- macro automodule(modname, options) -%} -.. automodule:: {{ modname }} -{%- for option in options %} - :{{ option }}: -{%- endfor %} -{%- endmacro %} - -{%- macro toctree(docnames) -%} -.. toctree:: - :maxdepth: {{ maxdepth }} -{% for docname in docnames %} - {{ docname }} -{%- endfor %} -{%- endmacro %} - -{%- if is_namespace %} -{{- pkgname | e | heading | title }} -{% else %} -{{- "API Reference" | e | heading }} -{% endif %} - -{%- if modulefirst and not is_namespace %} -{{ automodule(pkgname, automodule_options) }} -{% endif %} - -{%- if subpackages %} -Subpackages ------------ - -{{ toctree(subpackages) }} -{% endif %} - -{%- if submodules %} -{% if separatemodules %} -{{ toctree(submodules) }} -{% else %} -{%- for submodule in submodules %} -{% if show_headings %} -{{- submodule | e | heading(2) }} -{% endif %} -{{ automodule(submodule, automodule_options) }} -{% endfor %} -{%- endif %} -{%- endif %} - -{%- if not modulefirst and not is_namespace %} -Module contents ---------------- - -{{ automodule(pkgname, automodule_options) }} -{% endif %} \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..6138b614 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,33 @@ +site_name: "DiffSync Documentation" +site_url: "https://diffsync.readthedocs.io" +repo_url: "https://github.com/networktocode/diffsync" +site_description: "Library to easily sync/diff/update 2 different data sources" +site_author: "Network to Code, LLC " +edit_uri: "edit/main/diffsync/docs" +copyright: "© Copyright 2020-2021, Network to Code, LLC ." +theme: + name: "readthedocs" + navigation_depth: 4 +extra_css: + - "extra.css" +plugins: + - "search" + - "mkdocstrings" + - "include-markdown" +nav: + - Introduction: "index.md" + - Getting Started: "getting_started.md" + - License: "license.md" + - Examples: + - Using Multiple Data Sources: "examples/example1.md" + - Using a Callback Function: "examples/example2.md" + - API Reference: + - Module: + - DiffSync: "api_reference/diffsync.md" + - DiffSyncModel: "api_reference/diffsyncmodel.md" + - Diff: "api_reference/diff/index.md" + - Enum: "api_reference/enum/index.md" + - Exceptions: "api_reference/exceptions/index.md" + - Helpers: "api_reference/helpers/index.md" + - Logging: "api_reference/logging/index.md" + - Utils: "api_reference/utils/index.md" \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 2fdbc5fe..c70440e7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -23,11 +23,6 @@ colorama = {version = "^0.4.3", optional = true} # For Pydantic dataclasses = {version = "^0.7", python = "~3.6"} -# For RTD poetry integration -sphinx = {version = "^4.0.2", optional = true} -m2r2 = {version = "^0.2.7", optional = true} -sphinx-rtd-theme = {version = "^0.5.2", optional = true} -toml = {version = "^0.10.2", optional = true} [tool.poetry.dev-dependencies] pytest = "^6.1.0" @@ -43,21 +38,10 @@ mypy = "^0.782" pytest-cov = "^2.10.1" pytest-structlog = "^0.3" coverage = {extras = ["toml"], version = "^5.3"} -Sphinx = "^4.0.2" -m2r2 = "^0.2.7" -sphinx-rtd-theme = "^0.5.2" +mkdocs = "^1.2.1" +mkdocstrings = "^0.15.2" +mkdocs-include-markdown-plugin = "^3.1.4" -[tool.poetry.extras] -docs = [ - "sphinx", - "m2r2", - "toml", - "sphinx-rtd-theme", - "pydantic", - "structlog", - "colorama", - "dataclasses" -] [tool.black] line-length = 120 diff --git a/tasks.py b/tasks.py index c042640a..e3c35545 100644 --- a/tasks.py +++ b/tasks.py @@ -299,43 +299,3 @@ def tests(context, name=NAME, image_ver=IMAGE_VER, local=INVOKE_LOCAL): print("All tests have passed!") - -@task -def html(context, sourcedir="docs/source", builddir="docs/build"): - """Creates html docs using sphinx-build command. - - Args: - context (obj): Used to run specific commands - sourcedir (str, optional): Source directory for sphinx to use. Defaults to "source". - builddir (str, optional): Output directory for sphinx to use. Defaults to "build". - """ - print("Building html documentation...") - clean_docs(context, builddir) - command = f"sphinx-build {sourcedir} {builddir}" - context.run(command) - - -@task -def api_doc(context, sourcedir="diffsync", output="docs/source/api"): - """Creates api docs using sphinx-apidoc command. - - Args: - context (obj): Used to run specific commands - sourcedir (str, optional): Source directory for sphinx-apidoc to use. Defaults to "diffsync". - output (str, optional): Output dir for sphinx-apidoc to place rendered files. Defaults to "docs/source/api". - """ - print("Building api documentation...") - command = f"sphinx-apidoc -MTf -t docs/source/template/api -o {output} {sourcedir}" - context.run(command) - - -@task -def clean_docs(context, builddir="docs/build"): - """Removes the build directory and all of its contents. - - Args: - context (obj): Used to run specific commands - builddir (str, optional): Directory to be removed. Defaults to "build". - """ - print(f"Removing everything under {builddir} directory...") - context.run("rm -rf " + builddir) From 3960411eacf845783d0912f67320871328ae0a09 Mon Sep 17 00:00:00 2001 From: Josh Silvas Date: Wed, 23 Jun 2021 09:13:23 -0500 Subject: [PATCH 18/22] Updates poetry.extras for the docs --- pyproject.toml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/pyproject.toml b/pyproject.toml index c70440e7..8454a31f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -42,6 +42,11 @@ mkdocs = "^1.2.1" mkdocstrings = "^0.15.2" mkdocs-include-markdown-plugin = "^3.1.4" +[tool.poetry.extras] +docs = [ + "mkdocstrings", + "mkdocs-include-markdown-plugin" +] [tool.black] line-length = 120 From 09fac744265ca55a1b8762c7af75fb22e488b1bc Mon Sep 17 00:00:00 2001 From: Josh Silvas Date: Wed, 23 Jun 2021 09:16:39 -0500 Subject: [PATCH 19/22] Adds doc dependencies in as optional --- pyproject.toml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/pyproject.toml b/pyproject.toml index 8454a31f..33d508d1 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -23,6 +23,8 @@ colorama = {version = "^0.4.3", optional = true} # For Pydantic dataclasses = {version = "^0.7", python = "~3.6"} +mkdocstrings = {version = "^0.15.2", optional = true} +mkdocs-include-markdown-plugin = {version = "^3.1.4", optional = true} [tool.poetry.dev-dependencies] pytest = "^6.1.0" From 9885456560285fc1ee54efdd52131742b09be282 Mon Sep 17 00:00:00 2001 From: Josh Silvas Date: Wed, 23 Jun 2021 10:56:21 -0500 Subject: [PATCH 20/22] Revert to sphinx --- .readthedocs.yml | 5 +- README.md | 7 +- diffsync/__init__.py | 2 +- docs/api_reference/diff/index.md | 5 - docs/api_reference/diffsync.md | 4 - docs/api_reference/diffsyncmodel.md | 4 - docs/api_reference/enum/index.md | 5 - docs/api_reference/exceptions/index.md | 5 - docs/api_reference/helpers/index.md | 5 - docs/api_reference/logging/index.md | 5 - docs/api_reference/utils/index.md | 5 - docs/examples/example1.md | 4 - docs/examples/example2.md | 4 - docs/extra.css | 19 ---- docs/getting_started.md | 8 -- docs/index.md | 8 -- docs/license.md | 5 - docs/source/api/diffsync.rst | 56 +++++++++++ docs/source/conf.py | 99 +++++++++++++++++++ .../examples/01-multiple-data-sources.rst | 7 ++ docs/source/examples/02-callback-function.rst | 7 ++ docs/source/examples/index.rst | 9 ++ docs/source/getting_started/index.rst | 7 ++ docs/source/index.rst | 20 ++++ docs/source/license/index.rst | 5 + docs/source/overview/index.rst | 7 ++ docs/source/static/schema-page.css | 62 ++++++++++++ docs/source/static/theme_overrides.css | 13 +++ docs/source/template/api/package.rst_t | 51 ++++++++++ mkdocs.yml | 33 ------- pyproject.toml | 24 +++-- tasks.py | 40 ++++++++ 32 files changed, 407 insertions(+), 133 deletions(-) delete mode 100644 docs/api_reference/diff/index.md delete mode 100644 docs/api_reference/diffsync.md delete mode 100644 docs/api_reference/diffsyncmodel.md delete mode 100644 docs/api_reference/enum/index.md delete mode 100644 docs/api_reference/exceptions/index.md delete mode 100644 docs/api_reference/helpers/index.md delete mode 100644 docs/api_reference/logging/index.md delete mode 100644 docs/api_reference/utils/index.md delete mode 100644 docs/examples/example1.md delete mode 100644 docs/examples/example2.md delete mode 100644 docs/extra.css delete mode 100644 docs/getting_started.md delete mode 100644 docs/index.md delete mode 100644 docs/license.md create mode 100644 docs/source/api/diffsync.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/examples/01-multiple-data-sources.rst create mode 100644 docs/source/examples/02-callback-function.rst create mode 100644 docs/source/examples/index.rst create mode 100644 docs/source/getting_started/index.rst create mode 100644 docs/source/index.rst create mode 100644 docs/source/license/index.rst create mode 100644 docs/source/overview/index.rst create mode 100644 docs/source/static/schema-page.css create mode 100644 docs/source/static/theme_overrides.css create mode 100644 docs/source/template/api/package.rst_t delete mode 100644 mkdocs.yml diff --git a/.readthedocs.yml b/.readthedocs.yml index d19521d1..8d33d319 100644 --- 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 index 83d76aac..a66604f9 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ # DiffSync - + 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. - + # Getting started - + 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) ``` - \ No newline at end of file diff --git a/diffsync/__init__.py b/diffsync/__init__.py index 15c3c01e..44946067 100644 --- 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 deleted file mode 100644 index b12863e2..00000000 --- a/docs/api_reference/diff/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# DiffSync.Diff - -::: diffsync.diff - - diff --git a/docs/api_reference/diffsync.md b/docs/api_reference/diffsync.md deleted file mode 100644 index c98b639b..00000000 --- a/docs/api_reference/diffsync.md +++ /dev/null @@ -1,4 +0,0 @@ -# DiffSync - -::: diffsync.DiffSync - diff --git a/docs/api_reference/diffsyncmodel.md b/docs/api_reference/diffsyncmodel.md deleted file mode 100644 index 198348bb..00000000 --- a/docs/api_reference/diffsyncmodel.md +++ /dev/null @@ -1,4 +0,0 @@ -# DiffSync Model - -::: diffsync.DiffSyncModel - diff --git a/docs/api_reference/enum/index.md b/docs/api_reference/enum/index.md deleted file mode 100644 index d2234ef5..00000000 --- a/docs/api_reference/enum/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# DiffSync.Enum - -::: diffsync.enum - - diff --git a/docs/api_reference/exceptions/index.md b/docs/api_reference/exceptions/index.md deleted file mode 100644 index 416e33db..00000000 --- a/docs/api_reference/exceptions/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# DiffSync.Exceptions - -::: diffsync.exceptions - - diff --git a/docs/api_reference/helpers/index.md b/docs/api_reference/helpers/index.md deleted file mode 100644 index abfe7455..00000000 --- a/docs/api_reference/helpers/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# DiffSync.Helpers - -::: diffsync.helpers - - diff --git a/docs/api_reference/logging/index.md b/docs/api_reference/logging/index.md deleted file mode 100644 index 6256b77d..00000000 --- a/docs/api_reference/logging/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# DiffSync.Logging - -::: diffsync.logging - - diff --git a/docs/api_reference/utils/index.md b/docs/api_reference/utils/index.md deleted file mode 100644 index afeb11cf..00000000 --- a/docs/api_reference/utils/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# DiffSync.Utils - -::: diffsync.utils - - diff --git a/docs/examples/example1.md b/docs/examples/example1.md deleted file mode 100644 index 6fb468f0..00000000 --- a/docs/examples/example1.md +++ /dev/null @@ -1,4 +0,0 @@ -{% - include-markdown "../../examples/example1/README.md" - heading-offset=1 -%} diff --git a/docs/examples/example2.md b/docs/examples/example2.md deleted file mode 100644 index 8eb0cff9..00000000 --- a/docs/examples/example2.md +++ /dev/null @@ -1,4 +0,0 @@ -{% - include-markdown "../../examples/example2/README.md" - heading-offset=1 -%} diff --git a/docs/extra.css b/docs/extra.css deleted file mode 100644 index 85d51a14..00000000 --- a/docs/extra.css +++ /dev/null @@ -1,19 +0,0 @@ -/* Images */ -img { - display: block; - margin-left: auto; - margin-right: auto; -} - -/* Tables */ -table { - margin-bottom: 24px; - width: 100%; -} -th { - background-color: #f0f0f0; - padding: 6px; -} -td { - padding: 6px; -} \ No newline at end of file diff --git a/docs/getting_started.md b/docs/getting_started.md deleted file mode 100644 index 649bff10..00000000 --- a/docs/getting_started.md +++ /dev/null @@ -1,8 +0,0 @@ -# Getting Started - -{% - include-markdown "../README.md" - start="" - end="" - heading-offset=1 -%} diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index abc9ffa4..00000000 --- a/docs/index.md +++ /dev/null @@ -1,8 +0,0 @@ -# Welcome to the DiffSync Documentation! - -{% - include-markdown "../README.md" - start="" - end="" - heading-offset=1 -%} diff --git a/docs/license.md b/docs/license.md deleted file mode 100644 index a6de5c6f..00000000 --- a/docs/license.md +++ /dev/null @@ -1,5 +0,0 @@ -# License - -{% - include-markdown "../LICENSE" -%} diff --git a/docs/source/api/diffsync.rst b/docs/source/api/diffsync.rst new file mode 100644 index 00000000..473420e9 --- /dev/null +++ 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 new file mode 100644 index 00000000..ee551985 --- /dev/null +++ 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 new file mode 100644 index 00000000..b0d68c2c --- /dev/null +++ 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 \ No newline at end of file diff --git a/docs/source/examples/02-callback-function.rst b/docs/source/examples/02-callback-function.rst new file mode 100644 index 00000000..5abce420 --- /dev/null +++ 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 \ No newline at end of file diff --git a/docs/source/examples/index.rst b/docs/source/examples/index.rst new file mode 100644 index 00000000..60959e65 --- /dev/null +++ b/docs/source/examples/index.rst @@ -0,0 +1,9 @@ +############ +Examples +############ + +.. toctree:: + :maxdepth: 2 + + 01-multiple-data-sources + 02-callback-function \ No newline at end of file diff --git a/docs/source/getting_started/index.rst b/docs/source/getting_started/index.rst new file mode 100644 index 00000000..db41d096 --- /dev/null +++ b/docs/source/getting_started/index.rst @@ -0,0 +1,7 @@ +############### +Getting Started +############### + +.. mdinclude:: ../../../README.md + :start-line: 28 + :end-line: 153 \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..6d4d2c6d --- /dev/null +++ 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 new file mode 100644 index 00000000..112bcdff --- /dev/null +++ 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 new file mode 100644 index 00000000..89a03204 --- /dev/null +++ b/docs/source/overview/index.rst @@ -0,0 +1,7 @@ +********* +Overview +********* + +.. mdinclude:: ../../../README.md + :start-line: 2 + :end-line: 25 \ No newline at end of file diff --git a/docs/source/static/schema-page.css b/docs/source/static/schema-page.css new file mode 100644 index 00000000..78f9f02c --- /dev/null +++ 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; +} \ No newline at end of file diff --git a/docs/source/static/theme_overrides.css b/docs/source/static/theme_overrides.css new file mode 100644 index 00000000..63ee6cc7 --- /dev/null +++ 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/package.rst_t b/docs/source/template/api/package.rst_t new file mode 100644 index 00000000..621e6ea4 --- /dev/null +++ b/docs/source/template/api/package.rst_t @@ -0,0 +1,51 @@ +{%- macro automodule(modname, options) -%} +.. automodule:: {{ modname }} +{%- for option in options %} + :{{ option }}: +{%- endfor %} +{%- endmacro %} + +{%- macro toctree(docnames) -%} +.. toctree:: + :maxdepth: {{ maxdepth }} +{% for docname in docnames %} + {{ docname }} +{%- endfor %} +{%- endmacro %} + +{%- if is_namespace %} +{{- pkgname | e | heading | title }} +{% else %} +{{- "API Reference" | e | heading }} +{% endif %} + +{%- if modulefirst and not is_namespace %} +{{ automodule(pkgname, automodule_options) }} +{% endif %} + +{%- if subpackages %} +Subpackages +----------- + +{{ toctree(subpackages) }} +{% endif %} + +{%- if submodules %} +{% if separatemodules %} +{{ toctree(submodules) }} +{% else %} +{%- for submodule in submodules %} +{% if show_headings %} +{{- submodule | e | heading(2) }} +{% endif %} +{{ automodule(submodule, automodule_options) }} +{% endfor %} +{%- endif %} +{%- endif %} + +{%- if not modulefirst and not is_namespace %} +Module contents +--------------- + +{{ automodule(pkgname, automodule_options) }} +{% endif %} \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml deleted file mode 100644 index 6138b614..00000000 --- a/mkdocs.yml +++ /dev/null @@ -1,33 +0,0 @@ -site_name: "DiffSync Documentation" -site_url: "https://diffsync.readthedocs.io" -repo_url: "https://github.com/networktocode/diffsync" -site_description: "Library to easily sync/diff/update 2 different data sources" -site_author: "Network to Code, LLC " -edit_uri: "edit/main/diffsync/docs" -copyright: "© Copyright 2020-2021, Network to Code, LLC ." -theme: - name: "readthedocs" - navigation_depth: 4 -extra_css: - - "extra.css" -plugins: - - "search" - - "mkdocstrings" - - "include-markdown" -nav: - - Introduction: "index.md" - - Getting Started: "getting_started.md" - - License: "license.md" - - Examples: - - Using Multiple Data Sources: "examples/example1.md" - - Using a Callback Function: "examples/example2.md" - - API Reference: - - Module: - - DiffSync: "api_reference/diffsync.md" - - DiffSyncModel: "api_reference/diffsyncmodel.md" - - Diff: "api_reference/diff/index.md" - - Enum: "api_reference/enum/index.md" - - Exceptions: "api_reference/exceptions/index.md" - - Helpers: "api_reference/helpers/index.md" - - Logging: "api_reference/logging/index.md" - - Utils: "api_reference/utils/index.md" \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 33d508d1..34b19e6d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -23,8 +23,12 @@ colorama = {version = "^0.4.3", optional = true} # For Pydantic dataclasses = {version = "^0.7", python = "~3.6"} -mkdocstrings = {version = "^0.15.2", optional = true} -mkdocs-include-markdown-plugin = {version = "^3.1.4", optional = true} +# For RTD poetry integration +sphinx = {version = "^4.0.2", optional = true} +m2r2 = {version = "^0.2.7", optional = true} +sphinx-rtd-theme = {version = "^0.5.2", optional = true} +toml = {version = "^0.10.2", optional = true} + [tool.poetry.dev-dependencies] pytest = "^6.1.0" @@ -40,14 +44,20 @@ mypy = "^0.782" pytest-cov = "^2.10.1" pytest-structlog = "^0.3" coverage = {extras = ["toml"], version = "^5.3"} -mkdocs = "^1.2.1" -mkdocstrings = "^0.15.2" -mkdocs-include-markdown-plugin = "^3.1.4" +Sphinx = "^4.0.2" +m2r2 = "^0.2.7" +sphinx-rtd-theme = "^0.5.2" [tool.poetry.extras] docs = [ - "mkdocstrings", - "mkdocs-include-markdown-plugin" + "sphinx", + "m2r2", + "toml", + "sphinx-rtd-theme", + "pydantic", + "structlog", + "colorama", + "dataclasses" ] [tool.black] diff --git a/tasks.py b/tasks.py index e3c35545..c042640a 100644 --- a/tasks.py +++ b/tasks.py @@ -299,3 +299,43 @@ def tests(context, name=NAME, image_ver=IMAGE_VER, local=INVOKE_LOCAL): print("All tests have passed!") + +@task +def html(context, sourcedir="docs/source", builddir="docs/build"): + """Creates html docs using sphinx-build command. + + Args: + context (obj): Used to run specific commands + sourcedir (str, optional): Source directory for sphinx to use. Defaults to "source". + builddir (str, optional): Output directory for sphinx to use. Defaults to "build". + """ + print("Building html documentation...") + clean_docs(context, builddir) + command = f"sphinx-build {sourcedir} {builddir}" + context.run(command) + + +@task +def api_doc(context, sourcedir="diffsync", output="docs/source/api"): + """Creates api docs using sphinx-apidoc command. + + Args: + context (obj): Used to run specific commands + sourcedir (str, optional): Source directory for sphinx-apidoc to use. Defaults to "diffsync". + output (str, optional): Output dir for sphinx-apidoc to place rendered files. Defaults to "docs/source/api". + """ + print("Building api documentation...") + command = f"sphinx-apidoc -MTf -t docs/source/template/api -o {output} {sourcedir}" + context.run(command) + + +@task +def clean_docs(context, builddir="docs/build"): + """Removes the build directory and all of its contents. + + Args: + context (obj): Used to run specific commands + builddir (str, optional): Directory to be removed. Defaults to "build". + """ + print(f"Removing everything under {builddir} directory...") + context.run("rm -rf " + builddir) From 811af15298c2bec5247f600d4f365ce339fb192f Mon Sep 17 00:00:00 2001 From: Josh Silvas Date: Wed, 23 Jun 2021 11:06:23 -0500 Subject: [PATCH 21/22] Fixes separate pages for api reference. Updates README.md to address rendering error. Adds build directory to .gitignore --- .gitignore | 3 ++ README.md | 2 +- diffsync/__init__.py | 2 +- docs/source/api/diffsync.diff.rst | 7 ++++ docs/source/api/diffsync.enum.rst | 7 ++++ docs/source/api/diffsync.exceptions.rst | 7 ++++ docs/source/api/diffsync.helpers.rst | 7 ++++ docs/source/api/diffsync.logging.rst | 7 ++++ docs/source/api/diffsync.rst | 56 ++++--------------------- docs/source/api/diffsync.utils.rst | 7 ++++ docs/source/conf.py | 2 +- docs/source/template/api/module.rst_t | 9 ++++ 12 files changed, 66 insertions(+), 50 deletions(-) create mode 100644 docs/source/api/diffsync.diff.rst create mode 100644 docs/source/api/diffsync.enum.rst create mode 100644 docs/source/api/diffsync.exceptions.rst create mode 100644 docs/source/api/diffsync.helpers.rst create mode 100644 docs/source/api/diffsync.logging.rst create mode 100644 docs/source/api/diffsync.utils.rst create mode 100644 docs/source/template/api/module.rst_t diff --git a/.gitignore b/.gitignore index 5608daab..78344b0b 100644 --- a/.gitignore +++ b/.gitignore @@ -286,3 +286,6 @@ fabric.properties .vscode/* *.code-workspace + +## Sphinx Documentation ## +docs/build diff --git a/README.md b/README.md index a66604f9..e7f11c37 100644 --- 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 index 44946067..15c3c01e 100644 --- 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 new file mode 100644 index 00000000..9952e410 --- /dev/null +++ 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 new file mode 100644 index 00000000..da2be897 --- /dev/null +++ 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 new file mode 100644 index 00000000..9f2caa27 --- /dev/null +++ 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 new file mode 100644 index 00000000..c5128358 --- /dev/null +++ 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 new file mode 100644 index 00000000..a5884ba0 --- /dev/null +++ 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 index 473420e9..36349fc7 100644 --- a/docs/source/api/diffsync.rst +++ b/docs/source/api/diffsync.rst @@ -7,50 +7,12 @@ API Reference :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: +.. 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 new file mode 100644 index 00000000..4eb11a33 --- /dev/null +++ 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 index ee551985..070c9ccd 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -90,7 +90,7 @@ def remove_module_docstring(app, what, name, obj, options, lines): 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']}"]) + main(["-MTfe", "-t", f"{CURR_DIR}/template/api", "-o", f"{CURR_DIR}/api", f"{ROOT_DIR}/{TOOL_CONFIG['name']}"]) def setup(app): diff --git a/docs/source/template/api/module.rst_t b/docs/source/template/api/module.rst_t new file mode 100644 index 00000000..d9a50e6b --- /dev/null +++ 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 %} + From ca2a51e6fea444bc493e057f55621b8d9e3cc904 Mon Sep 17 00:00:00 2001 From: Josh Silvas Date: Wed, 23 Jun 2021 11:09:55 -0500 Subject: [PATCH 22/22] Removes api_doc invoke function as this is now handled via a sphinx callback --- tasks.py | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/tasks.py b/tasks.py index c042640a..fc138b10 100644 --- a/tasks.py +++ b/tasks.py @@ -315,20 +315,6 @@ def html(context, sourcedir="docs/source", builddir="docs/build"): context.run(command) -@task -def api_doc(context, sourcedir="diffsync", output="docs/source/api"): - """Creates api docs using sphinx-apidoc command. - - Args: - context (obj): Used to run specific commands - sourcedir (str, optional): Source directory for sphinx-apidoc to use. Defaults to "diffsync". - output (str, optional): Output dir for sphinx-apidoc to place rendered files. Defaults to "docs/source/api". - """ - print("Building api documentation...") - command = f"sphinx-apidoc -MTf -t docs/source/template/api -o {output} {sourcedir}" - context.run(command) - - @task def clean_docs(context, builddir="docs/build"): """Removes the build directory and all of its contents.