Add published API documentation (#24)

.python-version

@@ -1 +1 @@
-db_facts-3.8.2
+db_facts-3.8.3

DEVELOPMENT.md

@@ -28,3 +28,17 @@ db_facts>=a.x.y,<b.0.0
 
 This will make sure you don't get automatically updated into the next
 breaking change.
+
+## Documentation
+
+API reference documentation is pushed up to
+[readthedocs](https://db-facts.readthedocs.io/en/published_docs/) by a
+GitHub webhook.
+
+To create docs, run this from the `docs/` directory:
+
+* `make html`
+
+To view docs:
+
+* `open build/html/index.html`

Makefile

@@ -40,6 +40,18 @@ cicoverage: coverage
 flake8:
 	flake8 bluelabs_joblib tests
 
+quality-flake8:
+	make QUALITY_TOOL=flake8 quality
+
+quality-punchlist:
+	make QUALITY_TOOL=punchlist quality
+
+quality-bigfiles:
+	make QUALITY_TOOL=bigfiles quality
+
+quality-mdl:
+	make QUALITY_TOOL=mdl quality
+
 # to run a single item, you can do: make QUALITY_TOOL=bigfiles quality
 quality:
 	@quality_gem_version=$$(python -c 'import yaml; print(yaml.safe_load(open(".circleci/config.yml","r"))["quality_gem_version"])'); \

README.md

@@ -31,26 +31,26 @@ export DB_PROTOCOL
 DB_PROTOCOL=postgres
 ```
 
-To do this, it relies on a config file ("dbcli.yml") which teaches it
+For details on the potential facts returned, see the
+[API reference](https://db-facts.readthedocs.io/en/published_docs/db_facts.html#db_facts.DBFacts).
+
+`db-facts` relies on a config file ("dbcli.yml") which teaches it
 how to parse the user-friendly coordinates.  Much of the heavy lifting
 in the parsing part is done
 by
 [jinja_context.py](https://github.com/bluelabsio/db-facts/blob/master/db_facts/jinja_context.py),
 which sets some variables and functions that can be used in jinja
 templates within the config file.
 
-This is part of the suite of programs which allow a user to type in
-things like `db redshift` and connect via their own credentials to the
-configured database named 'redshift'.  Other parts of this chain can
-be found in the [ws-scripts](https://github.com/bluelabsio/ws-scripts)
-repo.
-
 If you need to set the instructions immediately to your environment
 variables, you can do this with the command:
 ```sh
 eval $(db-facts redshift)
 ```
 
+You can also access `db-facts` via a Python API; for details, see the
+[API reference](https://db-facts.readthedocs.io/en/published_docs/db_facts.html#module-db_facts).
+
 ## Configuration
 
 You can configure `db-facts` to connect to your databases.  See

db_facts/__init__.py

@@ -1,2 +1,10 @@
+__all__ = [
+    'db',
+    'DBFacts',
+    'UserErrorException'
+]
+
+from .errors import UserErrorException
+from .db_facts_types import DBFacts
 from .runner import Runner  # noqa - flake8 false positive
-from .db_info import db  # noqa - flake8 false positive
+from .db_info import db

db_facts/base64_jinja_context.py

@@ -6,6 +6,11 @@
 def pull_base64_jinja_context(db_name: DBName,
                               dbcli_config: DBCLIConfig) -> Tuple[JinjaContext,
                                                                   JinjaFilters]:
+    """Returns a Jinja context that exports the following functions:
+
+    * b64decode(s: str) -> str: Converts a base64ed string to its original contents.
+    * b64encode(s: str) -> str: Converts a string to its base64ed form.
+    """
     return ({},
             {
                 'b64decode': lambda s: base64.b64decode(s).decode('utf-8'),

db_facts/db_facts_types.py

@@ -18,16 +18,49 @@
     # databases, feel free to PR additions here (or maintain your own
     # type/ignore this one, of course).
     class DBFacts(TypedDict, total=False):
+        """This is a dictionary type which describes the output of the db()
+        method - a dict of various facts about the database in
+        question.  All keys are optional except 'type', and keys
+        should only be provided if relevant to the database type.
+        """
+
         user: str
+        "Database username"
+
         password: str
+        "Database password"
+
         host: str
+        "Database hostname"
+
         type: str
+        "Database type (canonical examples: postgres, vertica, mysql, redshift, bigquery)"
+
         protocol: str
+        """Database protocol type (often the same value as 'type', but may
+        vary for databases like Redshift which offer protocol
+        compatibilities with e.g. postgres)"""
+
         port: int
+        "Database port number"
+
         database: str
+        """Database name - this concepts varys quite a bit from database to
+        database, but is often used to distinguish between completely
+        separate databases that share the same underlying
+        infrastructure (e.g., same port and host, but different
+        database)."""
+
         bq_default_project_id: str
+        "BigQuery-specific - the project to be used if no specific project is specified"
+
         bq_default_dataset_id: str
+        "BigQuery-specific - the dataset to be used if no specific dataset is specified"
+
         bq_service_account_json: str
+        """BigQuery-specific - JSON (serialized to a string) representing the service account
+        credentials to be used."""
+
 else:
     DBFacts = Dict[str, Any]
 DBName = List[str]

db_facts/db_info.py

@@ -10,7 +10,11 @@
 
 
 def db(db_name: DBName, dbcli_config: DBCLIConfig = None) -> DBFacts:
-    """Get connection info for specified database."""
+    """Get connection info for specified database.
+
+    :param db_name: Alias for the particular database endpoint and account to connect to.  ['a','b','c'] corresponds to 'a-b-c' on the db-facts command-line.
+    :raises UserErrorException: Raised if db_name cannot be found.
+    """
 
     if dbcli_config is None:
         dbcli_config = load_config()

db_facts/env_jinja_context.py

@@ -3,6 +3,14 @@
 
 
 def pull_env_jinja_context(db_name: DBName, dbcli_config: DBCLIConfig) -> JinjaContext:
+    """Returns a Jinja context that exports the following functions:
+
+    * getenv(key: str, default: Optional[str]=None) -> Optional[str]:
+      Return the value of the environment variable key if it exists,
+      or default if it doesn’t. key, default and the result are str.
+    * env(key: str) -> str: Looks up an environment variable value, or
+      raises KeyError if not found.
+    """
     return {
         # Returns None if key not found unless default specified
         'getenv': os.getenv,

db_facts/errors.py

@@ -3,6 +3,9 @@
 
 
 class UserErrorException(Exception):
+    """
+    Raised upon an error related to the inputs to the db() function.
+    """
     pass
 
 

deps.sh

@@ -1,6 +1,6 @@
 #!/bin/bash -e
 
-python_version=3.8.2
+python_version=3.8.3
 # zipimport.ZipImportError: can't decompress data; zlib not available:
 #    You may need `xcode-select --install` on OS X
 #    https://github.com/pyenv/pyenv/issues/451#issuecomment-151336786

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     = source
+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/source/conf.py

@@ -0,0 +1,71 @@
+# 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('../../db-facts/'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'db-facts'
+copyright = '2020 BlueLabs Analytics, Inc.'
+author = 'Vince Broz'
+
+# The full version, including alpha/beta/rc tags
+release = '4.0.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',
+    # The default sphinx doesn't seem to set TYPE_CHECKING, which
+    # results in dropping our use of TypedDict, Literal and other
+    # things we don't use by default to avoid extra dependencies.
+    'sphinx_autodoc_typehints',
+]
+
+master_doc = 'index'
+
+# 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 = []
+
+
+# -- 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']
+
+
+# -- Options for type hint output --------------------------------------------
+
+#
+# Ensure TYPE_CHECKING is set to True so we document using types from
+# typing_extensions (e.g., TypedDict)
+#
+set_type_checking_flag = True

docs/source/db_facts.rst

@@ -0,0 +1,29 @@
+db\_facts package
+=================
+
+Submodules
+----------
+
+db\_facts.base64\_jinja\_context module
+---------------------------------------
+
+.. automodule:: db_facts.base64_jinja_context
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+db\_facts.env\_jinja\_context module
+------------------------------------
+
+.. automodule:: db_facts.env_jinja_context
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: db_facts
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/index.rst

@@ -0,0 +1,21 @@
+.. db-facts documentation master file, created by
+   sphinx-quickstart on Wed Jun  3 14:19:42 2020.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to db-facts's documentation!
+====================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   db_facts
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/source/modules.rst

@@ -0,0 +1,7 @@
+db_facts
+========
+
+.. toctree::
+   :maxdepth: 4
+
+   db_facts

metrics/coverage_high_water_mark

@@ -1 +1 @@
-97.9200
+97.9400

metrics/flake8_high_water_mark

@@ -1 +1 @@
-0
+1

metrics/mypy_high_water_mark

@@ -1 +1 @@
-72.7300
+73.1700

requirements.txt

@@ -8,3 +8,7 @@ mypy
 lxml # needed for mypy coverage report
 wheel # needed to publish to PyPI in CircleCI
 twine # needed to publish to PyPI in CircleCI
+sphinx # used to generate and upload docs
+sphinx-autodoc-typehints # used to handle type hints
+sphinx-rtd-theme # used to style docs for readthedocs.io
+recommonmark # used to be able to use sphinx with markdown