diff --git a/bigquery_datatransfer/docs/README.rst b/bigquery_datatransfer/docs/README.rst new file mode 120000 index 000000000000..89a0106941ff --- /dev/null +++ b/bigquery_datatransfer/docs/README.rst @@ -0,0 +1 @@ +../README.rst \ No newline at end of file diff --git a/bigquery_datatransfer/docs/conf.py b/bigquery_datatransfer/docs/conf.py index 4296369e17d6..af2063f5839b 100644 --- a/bigquery_datatransfer/docs/conf.py +++ b/bigquery_datatransfer/docs/conf.py @@ -20,12 +20,12 @@ # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.insert(0, os.path.abspath("..")) -__version__ = "0.15.4" +__version__ = "0.1.0" # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. -# needs_sphinx = '1.0' +needs_sphinx = "1.6.3" # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom @@ -36,6 +36,7 @@ "sphinx.ext.intersphinx", "sphinx.ext.coverage", "sphinx.ext.napoleon", + "sphinx.ext.todo", "sphinx.ext.viewcode", ] @@ -47,10 +48,14 @@ # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] +# Allow markdown includes (so releases.md can include CHANGLEOG.md) +# http://www.sphinx-doc.org/en/master/markdown.html +source_parsers = {".md": "recommonmark.parser.CommonMarkParser"} + # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # source_suffix = ['.rst', '.md'] -source_suffix = ".rst" +source_suffix = [".rst", ".md"] # The encoding of source files. # source_encoding = 'utf-8-sig' @@ -120,12 +125,20 @@ # 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 = "alabaster" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -# html_theme_options = {} +html_theme_options = { + "description": "Google Cloud Client Libraries for Python", + "github_user": "googleapis", + "github_repo": "google-cloud-python", + "github_banner": True, + "font_family": "'Roboto', Georgia, sans", + "head_font_family": "'Roboto', Georgia, serif", + "code_font_family": "'Roboto Mono', 'Consolas', monospace", +} # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] @@ -214,6 +227,17 @@ # Output file base name for HTML help builder. htmlhelp_basename = "google-cloud-bigquerydatatransfer-doc" +# -- Options for warnings ------------------------------------------------------ + +suppress_warnings = [ + # Temporarily suppress this to avoid "more than one target found for + # cross-reference" warning, which are intractable for us to avoid while in + # a mono-repo. + # See https://github.com/sphinx-doc/sphinx/blob + # /2a65ffeef5c107c19084fabdd706cdff3f52d93c/sphinx/domains/python.py#L843 + "ref.python" +] + # -- Options for LaTeX output --------------------------------------------- latex_elements = { @@ -310,6 +334,16 @@ intersphinx_mapping = { "python": ("http://python.readthedocs.org/en/latest/", None), "gax": ("https://gax-python.readthedocs.org/en/latest/", None), + "google-auth": ("https://google-auth.readthedocs.io/en/stable", None), + "google-gax": ("https://gax-python.readthedocs.io/en/latest/", None), + "google.api_core": ( + "https://googleapis.github.io/google-cloud-python/latest", + None, + ), + "grpc": ("https://grpc.io/grpc/python/", None), + "requests": ("http://docs.python-requests.org/en/master/", None), + "fastavro": ("https://fastavro.readthedocs.io/en/stable/", None), + "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None), } # Napoleon settings diff --git a/bigquery_datatransfer/docs/index.rst b/bigquery_datatransfer/docs/index.rst index c756b78dc9a4..942e2634213c 100644 --- a/bigquery_datatransfer/docs/index.rst +++ b/bigquery_datatransfer/docs/index.rst @@ -1,4 +1,4 @@ -.. include:: /../bigquery_datatransfer/README.rst +.. include:: README.rst API Reference diff --git a/bigquery_datatransfer/noxfile.py b/bigquery_datatransfer/noxfile.py index e424e1c7ba62..a30d9a8bd808 100644 --- a/bigquery_datatransfer/noxfile.py +++ b/bigquery_datatransfer/noxfile.py @@ -16,6 +16,7 @@ from __future__ import absolute_import import os +import shutil import nox @@ -138,3 +139,22 @@ def cover(session): session.run("coverage", "report", "--show-missing", "--fail-under=79") session.run("coverage", "erase") + +@nox.session(python="3.7") +def docs(session): + """Build the docs for this library.""" + + session.install('-e', '.') + session.install('sphinx', 'alabaster', 'recommonmark') + + shutil.rmtree(os.path.join('docs', '_build'), ignore_errors=True) + session.run( + 'sphinx-build', + '-W', # warnings as errors + '-T', # show full traceback on exception + '-N', # no colors + '-b', 'html', + '-d', os.path.join('docs', '_build', 'doctrees', ''), + os.path.join('docs', ''), + os.path.join('docs', '_build', 'html', ''), + ) diff --git a/bigquery_datatransfer/synth.metadata b/bigquery_datatransfer/synth.metadata index 1b47390f4848..7c330947a0a0 100644 --- a/bigquery_datatransfer/synth.metadata +++ b/bigquery_datatransfer/synth.metadata @@ -1,11 +1,19 @@ { - "updateTime": "2019-04-12T17:01:24.063249Z", + "updateTime": "2019-04-23T12:11:35.129747Z", "sources": [ { "generator": { "name": "artman", - "version": "0.16.25", - "dockerImage": "googleapis/artman@sha256:d9597f983d1d4e61272c63cb97b7d8f8234da9999526c35d357de3d781f0ec1b" + "version": "0.17.0", + "dockerImage": "googleapis/artman@sha256:c58f4ec3838eb4e0718eb1bccc6512bd6850feaa85a360a9e38f6f848ec73bc2" + } + }, + { + "git": { + "name": "googleapis", + "remote": "https://github.com/googleapis/googleapis.git", + "sha": "547e19e7df398e9290e8e3674d7351efc500f9b0", + "internalRef": "244712781" } }, {