Add initial sphinx docs

Signed-off-by: Ivan Schaller <ivan@schaller.sh>

.gitignore

@@ -17,3 +17,4 @@ octodns.egg-info/
 output/
 tests/zones/unit.tests.
 tmp/
+docs/_build/

docs/build_docs.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+
+set -xeuo pipefail
+
+rm -rf docs/_build
+sphinx-build -M html docs docs/_build "${@}"

docs/conf.py

@@ -0,0 +1,90 @@
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path("..", "src").resolve()))
+
+from octodns.__init__ import __version__
+
+### sphinx config ###
+
+project = "octodns"
+copyright = "2017-present"  # noqa
+author = "Ross McFarland"
+release = __version__
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.coverage",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
+    "myst_parser",
+    "sphinx_copybutton",
+]
+
+
+### autodoc ###
+
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+    "private-members": False,
+    "special-members": "__init__",
+    "show-inheritance": True,
+    "exclude-members": "__weakref__",
+}
+autodoc_typehints = "both"
+autodoc_typehints_description_target = "all"
+autodoc_member_order = "alphabetical"
+
+### extlinks ###
+
+extlinks = {
+    "github": ("https://github.com/%s", "%s"),
+    "pypi": ("https://pypi.org/project/%s/", "%s"),
+}
+extlinks_detect_hardcoded_links = True
+
+
+### intersphinx ###
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master", None),
+    "dnspython": ("https://dnspython.readthedocs.io/en/stable/", None),
+}
+
+
+### todo ###
+
+todo_include_todos = True
+
+
+### myst ###
+
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+]
+myst_heading_anchors = 3
+
+
+### content ###
+
+master_doc = "index"
+
+templates_path = ["_templates"]
+html_static_path = ["_static"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+### theme ###
+
+# tml_theme = "alabaster"
+html_theme = "furo"
+html_theme_options = {
+    "source_repository": "https://github.com/octodns/octodns/",
+    "source_branch": "main",
+    "source_directory": "docs/",
+}

docs/get_docs.py

@@ -0,0 +1,28 @@
+from pathlib import Path
+
+SRCDIR = Path("octodns")
+DOC_MODULE_DIR = Path("docs/modules")
+
+DOC_MODULE_TEMPLATE = """
+====================================
+``{module_name}``
+====================================
+
+.. automodule:: {module_name}"""
+
+for module in SRCDIR.rglob("*.py"):
+    if module.name in ["__init__.py", "__about__.py"]:
+        continue
+
+    module_docname = str(module).replace("/", ".").removesuffix(".py")
+
+    if module.parent.name != "octodns":
+        module_docpath = DOC_MODULE_DIR / module.parent.name / f"{module_docname}.rst"
+    else:
+        module_docpath = DOC_MODULE_DIR / f"{module_docname}.rst"
+
+    print(f"creating sphinx doc module for: {module_docname}")
+    module_docpath.parent.mkdir(exist_ok=True, parents=True)
+    module_docpath.write_text(
+        DOC_MODULE_TEMPLATE.format(module_name=module_docname).strip()
+    )

docs/index.md

@@ -0,0 +1,74 @@
+# octodns documentation
+
+```{include} ../README.md
+:end-before: "## Table of Contents"
+```
+
+---
+
+## Indices and tables
+
+- {ref}`genindex`
+- {ref}`modindex`
+
+### Project infos
+
+- [License](infos/license.md)
+- [Changelog](infos/changelog.md)
+
+---
+
+## User documentation
+
+```{toctree}
+:caption: Guides:
+:maxdepth: 1
+:glob:
+
+```
+
+---
+
+## Module documentation
+
+```{toctree}
+:caption: Processors:
+:maxdepth: 2
+:glob:
+
+modules/processor/*
+```
+
+```{toctree}
+:caption: Providers:
+:maxdepth: 2
+:glob:
+
+modules/provider/*
+```
+
+```{toctree}
+:caption: Sources:
+:maxdepth: 2
+:glob:
+
+modules/source/*
+```
+
+```{toctree}
+:caption: Records:
+:maxdepth: 2
+:glob:
+
+modules/record/*
+```
+
+```{toctree}
+:caption: Other modules:
+:titlesonly:
+:glob:
+
+modules/*
+modules/cmds/*
+modules/secret/*
+```

docs/infos/changelog.md

@@ -0,0 +1,5 @@
+# Changelog
+
+```{include} ../../CHANGELOG.md
+
+```

docs/infos/license.md

@@ -0,0 +1,5 @@
+# License
+
+```{include} ../../LICENSE
+
+```

docs/modules/cmds/octodns.cmds.args.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.cmds.args``
+====================================
+
+.. automodule:: octodns.cmds.args

docs/modules/cmds/octodns.cmds.compare.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.cmds.compare``
+====================================
+
+.. automodule:: octodns.cmds.compare

docs/modules/cmds/octodns.cmds.dump.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.cmds.dump``
+====================================
+
+.. automodule:: octodns.cmds.dump

docs/modules/cmds/octodns.cmds.report.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.cmds.report``
+====================================
+
+.. automodule:: octodns.cmds.report

docs/modules/cmds/octodns.cmds.sync.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.cmds.sync``
+====================================
+
+.. automodule:: octodns.cmds.sync

docs/modules/cmds/octodns.cmds.validate.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.cmds.validate``
+====================================
+
+.. automodule:: octodns.cmds.validate

docs/modules/cmds/octodns.cmds.versions.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.cmds.versions``
+====================================
+
+.. automodule:: octodns.cmds.versions

docs/modules/octodns.context.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.context``
+====================================
+
+.. automodule:: octodns.context

docs/modules/octodns.deprecation.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.deprecation``
+====================================
+
+.. automodule:: octodns.deprecation

docs/modules/octodns.equality.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.equality``
+====================================
+
+.. automodule:: octodns.equality

docs/modules/octodns.idna.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.idna``
+====================================
+
+.. automodule:: octodns.idna

docs/modules/octodns.manager.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.manager``
+====================================
+
+.. automodule:: octodns.manager

docs/modules/octodns.yaml.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.yaml``
+====================================
+
+.. automodule:: octodns.yaml

docs/modules/octodns.zone.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.zone``
+====================================
+
+.. automodule:: octodns.zone

docs/modules/processor/octodns.processor.acme.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.processor.acme``
+====================================
+
+.. automodule:: octodns.processor.acme

docs/modules/processor/octodns.processor.arpa.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.processor.arpa``
+====================================
+
+.. automodule:: octodns.processor.arpa

docs/modules/processor/octodns.processor.base.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.processor.base``
+====================================
+
+.. automodule:: octodns.processor.base

docs/modules/processor/octodns.processor.filter.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.processor.filter``
+====================================
+
+.. automodule:: octodns.processor.filter

docs/modules/processor/octodns.processor.meta.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.processor.meta``
+====================================
+
+.. automodule:: octodns.processor.meta

docs/modules/processor/octodns.processor.ownership.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.processor.ownership``
+====================================
+
+.. automodule:: octodns.processor.ownership

docs/modules/processor/octodns.processor.restrict.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.processor.restrict``
+====================================
+
+.. automodule:: octodns.processor.restrict

docs/modules/processor/octodns.processor.spf.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.processor.spf``
+====================================
+
+.. automodule:: octodns.processor.spf

docs/modules/processor/octodns.processor.trailing_dots.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.processor.trailing_dots``
+====================================
+
+.. automodule:: octodns.processor.trailing_dots

docs/modules/provider/octodns.provider.base.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.provider.base``
+====================================
+
+.. automodule:: octodns.provider.base

docs/modules/provider/octodns.provider.plan.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.provider.plan``
+====================================
+
+.. automodule:: octodns.provider.plan

docs/modules/provider/octodns.provider.yaml.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.provider.yaml``
+====================================
+
+.. automodule:: octodns.provider.yaml

docs/modules/record/octodns.record.a.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.a``
+====================================
+
+.. automodule:: octodns.record.a

docs/modules/record/octodns.record.aaaa.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.aaaa``
+====================================
+
+.. automodule:: octodns.record.aaaa

docs/modules/record/octodns.record.alias.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.alias``
+====================================
+
+.. automodule:: octodns.record.alias

docs/modules/record/octodns.record.base.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.base``
+====================================
+
+.. automodule:: octodns.record.base

docs/modules/record/octodns.record.caa.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.caa``
+====================================
+
+.. automodule:: octodns.record.caa

docs/modules/record/octodns.record.change.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.change``
+====================================
+
+.. automodule:: octodns.record.change

docs/modules/record/octodns.record.chunked.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.chunked``
+====================================
+
+.. automodule:: octodns.record.chunked

docs/modules/record/octodns.record.cname.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.cname``
+====================================
+
+.. automodule:: octodns.record.cname

docs/modules/record/octodns.record.dname.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.dname``
+====================================
+
+.. automodule:: octodns.record.dname

docs/modules/record/octodns.record.ds.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.ds``
+====================================
+
+.. automodule:: octodns.record.ds

docs/modules/record/octodns.record.dynamic.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.dynamic``
+====================================
+
+.. automodule:: octodns.record.dynamic

docs/modules/record/octodns.record.exception.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.exception``
+====================================
+
+.. automodule:: octodns.record.exception

docs/modules/record/octodns.record.geo.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.geo``
+====================================
+
+.. automodule:: octodns.record.geo

docs/modules/record/octodns.record.geo_data.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.geo_data``
+====================================
+
+.. automodule:: octodns.record.geo_data

docs/modules/record/octodns.record.https.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.https``
+====================================
+
+.. automodule:: octodns.record.https

docs/modules/record/octodns.record.ip.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.ip``
+====================================
+
+.. automodule:: octodns.record.ip

docs/modules/record/octodns.record.loc.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.loc``
+====================================
+
+.. automodule:: octodns.record.loc

docs/modules/record/octodns.record.mx.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.mx``
+====================================
+
+.. automodule:: octodns.record.mx

docs/modules/record/octodns.record.naptr.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.naptr``
+====================================
+
+.. automodule:: octodns.record.naptr

docs/modules/record/octodns.record.ns.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.ns``
+====================================
+
+.. automodule:: octodns.record.ns

docs/modules/record/octodns.record.ptr.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.ptr``
+====================================
+
+.. automodule:: octodns.record.ptr

docs/modules/record/octodns.record.rr.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.rr``
+====================================
+
+.. automodule:: octodns.record.rr

docs/modules/record/octodns.record.spf.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.spf``
+====================================
+
+.. automodule:: octodns.record.spf

docs/modules/record/octodns.record.srv.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.srv``
+====================================
+
+.. automodule:: octodns.record.srv

docs/modules/record/octodns.record.sshfp.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.sshfp``
+====================================
+
+.. automodule:: octodns.record.sshfp

docs/modules/record/octodns.record.subnet.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.subnet``
+====================================
+
+.. automodule:: octodns.record.subnet

docs/modules/record/octodns.record.svcb.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.svcb``
+====================================
+
+.. automodule:: octodns.record.svcb

docs/modules/record/octodns.record.target.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.target``
+====================================
+
+.. automodule:: octodns.record.target

docs/modules/record/octodns.record.tlsa.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.tlsa``
+====================================
+
+.. automodule:: octodns.record.tlsa

docs/modules/record/octodns.record.txt.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.txt``
+====================================
+
+.. automodule:: octodns.record.txt

docs/modules/record/octodns.record.urlfwd.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.record.urlfwd``
+====================================
+
+.. automodule:: octodns.record.urlfwd

docs/modules/secret/octodns.secret.base.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.secret.base``
+====================================
+
+.. automodule:: octodns.secret.base

docs/modules/secret/octodns.secret.environ.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.secret.environ``
+====================================
+
+.. automodule:: octodns.secret.environ

docs/modules/secret/octodns.secret.exception.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.secret.exception``
+====================================
+
+.. automodule:: octodns.secret.exception

docs/modules/source/octodns.source.base.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.source.base``
+====================================
+
+.. automodule:: octodns.source.base

docs/modules/source/octodns.source.envvar.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.source.envvar``
+====================================
+
+.. automodule:: octodns.source.envvar

docs/modules/source/octodns.source.tinydns.rst

@@ -0,0 +1,5 @@
+====================================
+``octodns.source.tinydns``
+====================================
+
+.. automodule:: octodns.source.tinydns

docs/pages/quick-start.md

@@ -0,0 +1,6 @@
+# Quick-Start
+
+```{include} ../../README.md
+:start-after: "## Getting started"
+:end-before: "## Providers"
+```