Launch SDK docs website

.gitignore

@@ -1,3 +1,7 @@
+# Sphinx documentation
+
+**/_build
+
 # Ignore secrets folders used in testing (except readme and templates)
 
 **/.secrets/*

.readthedocs.yml

@@ -0,0 +1,14 @@
+version: 2
+
+sphinx:
+  builder: html
+  configuration: docs/conf.py
+
+python:
+  version: 3.8
+  install:
+    # - requirements: docs/requirements.txt
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

README.md

@@ -1,62 +1,22 @@
-# `singer-sdk` - a framework for building Singer taps
+# Meltano SDK for Taps and Targets
 
-## Less is More
+The Tap and Target SDKs are the fastest way to build custom data extractors and loaders!
+Taps and targets built on the SDK are automatically compliant with the
+[Singer Spec](https://meltano.com/docs/singer-spec.html), the
+de-facto open source standard for extract and load pipelines.
 
-Because taps built from the SDK require substantially less code, developers are able to dramatically reduce the time to develop a fully mature Singer tap.
+## Future-proof extractors and loaders, with less code
 
-## Build Future-Proof Data Extractors
+On average, developers tell us that they write about 70% less code by using the SDK, which
+makes learning the SDK a great investment. Furthermore, as new features and capabilities
+are added to the SDK, your taps and targets can always take advantage of the latest
+capabilities and bug fixes, simply by updating your SDK dependency to the latest version.
 
-We will continue to add new features to the SDK. You can always take advantage of the latest capabilities by simply updating your SDK version and then retesting and republishing with the latest version.
+## Documentation
 
-## Cookie-Cutter Quick Start
-
-`Singer SDK` provides a quickstart `cookiecutter` template for starting new taps.
-
-* [Click here for the **Cookiecutter Tap Template**](cookiecutter/tap-template/README.md)
-
-## Tap Dev Guide
-
-See the [dev guide](docs/dev_guide.md) for instructions on how to get started building your own
-taps.
-
-## Singer SDK Implementation Details
-
-For more detailed information about the Singer SDK implementation, please see the 
-[Singer SDK Implementation Details](./docs/implementation/README.md) section.
+- See our [online documentation](https://meltano-sdk.readthedocs.io) for instructions on how
+to get started with the SDK.
 
 ## Contributing back to the SDK
 
-First clone, then...
-
-### Install
-
-_**Note:** Singer SDK currently works with Python versions 3.6 through 3.8.x. Python 3.9 is not yet supported._
-
-Install prereqs:
-
-```bash
-pip3 install pipx
-pipx ensurepath
-pipx install poetry
-```
-
-Install package dependencies:
-
-```bash
-cd singer-sdk
-```
-
-```bash
-# Install package and dependencies:
-poetry install
-# OR install in editable mode:
-poetry install --no-root
-```
-
-- For more information, see our [Contributors Guide](CONTRIBUTING.md).
-
-### Run tests
-
-```bash
-poetry run pytest
-```
+- For more information on how to contribute, see our [Contributors Guide](CONTRIBUTING.md).

cookiecutter/tap-template/README.md

@@ -1,4 +1,4 @@
-# Singer SDK Tap Template
+# Singer Tap Template
 
 To use this cookie cutter template:
 

cookiecutter/tap-template/{{cookiecutter.tap_id}}/README.md

@@ -2,7 +2,7 @@
 
 `{{ cookiecutter.tap_id }}` is a Singer tap for {{ cookiecutter.source_name }}.
 
-Build with the [Singer SDK](https://gitlab.com/meltano/singer-sdk).
+Built with the Meltano [SDK](https://gitlab.com/meltano/singer-sdk) for Singer Taps.
 
 ## Installation
 
@@ -94,7 +94,7 @@ meltano invoke {{ cookiecutter.tap_id }} --version
 meltano elt {{ cookiecutter.tap_id }} target-jsonl
 ```
 
-### Singer SDK Dev Guide
+### SDK Dev Guide
 
-See the [dev guide](https://gitlab.com/meltano/singer-sdk/-/blob/main/docs/dev_guide.md) for more instructions on how to use the Singer SDK to 
+See the [dev guide](https://gitlab.com/meltano/singer-sdk/-/blob/main/docs/dev_guide.md) for more instructions on how to use the SDK to 
 develop your own taps and targets.

cookiecutter/tap-template/{{cookiecutter.tap_id}}/pyproject.toml

@@ -1,7 +1,7 @@
 [tool.poetry]
 name = "{{cookiecutter.tap_id}}"
 version = "0.0.1"
-description = "`{{cookiecutter.tap_id}}` is Singer tap for {{cookiecutter.source_name}}, built with the Singer SDK."
+description = "`{{cookiecutter.tap_id}}` is a Singer tap for {{cookiecutter.source_name}}, built with the Meltano SDK for Singer Taps."
 authors = ["{{ cookiecutter.admin_name }}"]
 license = "Apache 2.0"
 

docs/CONTRIBUTING.md

@@ -1,7 +1,34 @@
-# Contributing to the Singer SDK
+# Contributing to the SDK
+
+_**Note:** The SDK currently works with Python versions 3.6 through 3.8.x. Python 3.9 is not yet supported._
+
+## Setting up Prereqs
+
+If poetry and pipx are not already installed:
+
+```bash
+pip3 install pipx
+pipx ensurepath
+pipx install poetry
+```
+
+Now you can use Poetry to install package dependencies:
+
+```bash
+cd singer-sdk
+```
+
+```bash
+# Install package and dependencies:
+poetry install
+# OR install in editable mode:
+poetry install --no-root
+```
 
 ## Local Developer Setup
 
+First clone, then...
+
 1. If you are using VS Code, make sure you have also installed the `Python` extension.
 2. Ensure you have the correct test library, formatters, and linters installed:
     - `poetry install`
@@ -45,8 +72,37 @@ To run all tests:
 poetry run tox
 ```
 
+## Testing Updates to Docs
+
+Documentation runs on Sphinx, a using ReadtheDocs style template, and hosting from
+ReadtheDocs.org. When a push is detected by readthedocs.org, they automatically rebuild
+and republish the docs. ReadtheDocs is also version aware, so it retains prior and unreleased
+versions of the docs for us.
 
-## Workspace Development Strategies for Singer SDK
+First, make sure your virtual env has all the right tools and versions:
+
+```bash
+poetry install
+```
+
+To build the docs:
+
+```bash
+cd docs
+# Build docs
+poetry run make html
+# Open in the local browser:
+open _build/html/index.html
+```
+
+To build missing stubs:
+
+```bash
+cd docs
+poetry run sphinx-autogen -o classes *.rst
+```
+
+## Workspace Development Strategies for the SDK
 
 ### Universal Code Formatting
 
@@ -56,3 +112,8 @@ poetry run tox
 ### Pervasive Python Type Hints
 
 Type hints allow us to spend less time reading documentation.
+
+### What is Poetry and why do we need it?
+
+For more info on `Poetry` and `Pipx`, please see the topic in our
+[python tips](python_tips.md) guide.

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_templates/footer.html

@@ -0,0 +1,9 @@
+{% extends '!footer.html' %}
+{% block extrafooter %}
+
+    The SDK is built with love by the <a href="https://meltano.com">Meltano</a> core team and contributors, with
+    contributions from developers across the <a href="https://singer.io">Singer</a> open source community.
+
+    <!-- Docs built using <a href="https://www.sphinx-doc.org">Sphinx</a> and <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a> 
+    from <a href="https://readthedocs.org">Read the Docs</a>. -->
+{% endblock %}

docs/classes/singer_sdk.GraphQLStream.rst

@@ -0,0 +1,7 @@
+singer\_sdk.GraphQLStream
+=========================
+
+.. currentmodule:: singer_sdk
+
+.. autoclass:: GraphQLStream
+    :members:

docs/classes/singer_sdk.RESTStream.rst

@@ -0,0 +1,7 @@
+singer\_sdk.RESTStream
+======================
+
+.. currentmodule:: singer_sdk
+
+.. autoclass:: RESTStream
+    :members:

docs/classes/singer_sdk.Stream.rst

@@ -0,0 +1,7 @@
+singer\_sdk.Stream
+==================
+
+.. currentmodule:: singer_sdk
+
+.. autoclass:: Stream
+    :members:

docs/classes/singer_sdk.Tap.rst

@@ -0,0 +1,7 @@
+singer\_sdk.Tap
+===============
+
+.. currentmodule:: singer_sdk
+
+.. autoclass:: Tap
+    :members:

docs/classes/singer_sdk.authenticators.OAuthAuthenticator.rst

@@ -0,0 +1,7 @@
+singer\_sdk.authenticators.OAuthAuthenticator
+=============================================
+
+.. currentmodule:: singer_sdk.authenticators
+
+.. autoclass:: OAuthAuthenticator
+    :members:

docs/classes/singer_sdk.authenticators.OAuthJWTAuthenticator.rst

@@ -0,0 +1,7 @@
+singer\_sdk.authenticators.OAuthJWTAuthenticator
+================================================
+
+.. currentmodule:: singer_sdk.authenticators
+
+.. autoclass:: OAuthJWTAuthenticator
+    :members:

docs/classes/singer_sdk.authenticators.SimpleAuthenticator.rst

@@ -0,0 +1,7 @@
+singer\_sdk.authenticators.SimpleAuthenticator
+==============================================
+
+.. currentmodule:: singer_sdk.authenticators
+
+.. autoclass:: SimpleAuthenticator
+    :members:

docs/classes/singer_sdk.exceptions.TapStreamConnectionFailure.rst

@@ -0,0 +1,6 @@
+singer\_sdk.exceptions.TapStreamConnectionFailure
+=================================================
+
+.. currentmodule:: singer_sdk.exceptions
+
+.. autoexception:: TapStreamConnectionFailure

docs/classes/singer_sdk.exceptions.TooManyRecordsException.rst

@@ -0,0 +1,6 @@
+singer\_sdk.exceptions.TooManyRecordsException
+==============================================
+
+.. currentmodule:: singer_sdk.exceptions
+
+.. autoexception:: TooManyRecordsException

docs/conf.py

@@ -0,0 +1,63 @@
+# 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
+
+sys.path.insert(0, os.path.abspath(".."))
+# sys.path.insert(0, os.path.abspath("../singer_sdk"))
+# sys.path.insert(0, os.path.abspath("/Users/ajsteers/Source/singer-sdk"))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "Meltano SDK"
+copyright = "2021, Meltano Core Team and Contributors"
+author = "Meltano Core Team and Contributors"
+
+# The full version, including alpha/beta/rc tags
+release = "0.2.0"
+
+
+# -- 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.autosummary",
+    "sphinx_rtd_theme",
+    "sphinx_copybutton",
+    "myst_parser",
+]
+
+# 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"]