Port of @olofvndrhr, structure/setup from #1261

.changelog/88a37c98bbcf4ea58b57854afb46b73c.md

@@ -0,0 +1,4 @@
+---
+type: none
+---
+Add sphinx doc generation

.gitignore

@@ -2,18 +2,20 @@
 # Do not add editor or OS specific ignores here. Have a look at adding
 # `excludesfile` to your `~/.gitconfig` to globally ignore such things.
 #
-*.pyc
-.coverage
-.env
 /build/
 /config/
+.coverage
 coverage.xml
 dist/
+docs/_build/
+docs/modules/
+.env
 env/
 examples/migrating-to-octodns/config/
 htmlcov/
 nosetests.xml
 octodns.egg-info/
 output/
+*.pyc
 tests/zones/unit.tests.
 tmp/

docs/conf.py

@@ -0,0 +1,96 @@
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent.resolve()))
+
+print(f"SYS.PATH={sys.path}")
+
+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": True,
+    "special-members": "__init__, __repr__",
+    # "inherited-members": True,
+    "exclude-members": "__weakref__",
+    "show-inheritance": True,
+}
+autodoc_typehints = "both"
+autodoc_typehints_description_target = "all"
+autodoc_member_order = "bysource"
+
+### 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),
+    "six": ("https://six.readthedocs.io/", None),
+    "python-dateutil": ("https://dateutil.readthedocs.io/en/stable/", None),
+    "fqdn": ("https://fqdn.readthedocs.io/en/latest/", 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 ###
+
+# html_theme = "alabaster"
+html_theme = "furo"
+html_theme_options = {
+    "source_repository": "https://github.com/octodns/octodns/",
+    "source_branch": "main",
+    "source_directory": "docs/",
+}

docs/index.md

@@ -0,0 +1,77 @@
+# octodns documentation
+
+```{include} ../README.md
+---
+end-before: '## Table of Contents'
+---
+```
+
+______________________________________________________________________
+
+## Indices and tables
+
+- {ref}`genindex`
+- {ref}`modindex`
+
+### Project info
+
+- [License](info/license.md)
+- [Changelog](info/changelog.md)
+
+______________________________________________________________________
+
+## User documentation
+
+```{toctree}
+:caption: Guides:
+:maxdepth: 1
+:glob:
+
+*
+```
+
+______________________________________________________________________
+
+## Module documentation
+
+```{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: Processors:
+:maxdepth: 2
+:glob:
+
+modules/processor/*
+```
+
+```{toctree}
+:caption: Other modules:
+:titlesonly:
+:glob:
+
+modules/*
+modules/cmds/*
+modules/secret/*
+```

docs/info/changelog.md

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

docs/info/license.md

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

script/generate-docs

@@ -0,0 +1,23 @@
+#!/bin/bash
+
+set -e
+
+cd "$(dirname "$0")/.."
+ROOT=$(pwd)
+cd "$ROOT"
+
+rm -rf ./docs/_build ./docs/modules
+
+for f in $(find octodns -name "*.py" | grep -v __init__.py); do
+    module_name=$(echo $f | sed -e 's#/#.#g' -e 's/.py//')
+    outdir="docs/modules$(dirname $f | sed -e 's#octodns##')"
+    mkdir -p "$outdir"
+    cat <<EOL > "${outdir}/${module_name}.rst"
+====================================
+``${module_name}``
+====================================
+.. automodule:: ${module_name}
+EOL
+done
+
+sphinx-build -M html "${ROOT}/docs" "${ROOT}/docs/_build" "$@"