From 1f21ea5bfadd2e3100f54b4b28d8f8812a60f55e Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Tue, 11 Sep 2018 14:09:22 -0400 Subject: [PATCH] Prep storage docs for repo split. - Move docs from 'docs/storage' into 'storage/docs' and leave symlink. - Harmonize / DRY 'storage/README.rst' and 'storage/docs/index.rst'. - Ensure that docs still build from top-level. Toward #5912. --- docs/index.rst | 2 +- docs/storage | 1 + docs/storage/changelog.md | 1 - docs/storage/client.rst | 37 --- storage/README.rst | 89 +++--- {docs/storage => storage/docs}/acl.rst | 0 {docs/storage => storage/docs}/batch.rst | 0 {docs/storage => storage/docs}/blobs.rst | 0 {docs/storage => storage/docs}/buckets.rst | 0 storage/docs/changelog.md | 1 + storage/docs/client.rst | 6 + storage/docs/conf.py | 317 +++++++++++++++++++++ storage/docs/index.rst | 21 ++ {docs/storage => storage/docs}/snippets.py | 0 14 files changed, 400 insertions(+), 75 deletions(-) create mode 120000 docs/storage delete mode 120000 docs/storage/changelog.md delete mode 100644 docs/storage/client.rst rename {docs/storage => storage/docs}/acl.rst (100%) rename {docs/storage => storage/docs}/batch.rst (100%) rename {docs/storage => storage/docs}/blobs.rst (100%) rename {docs/storage => storage/docs}/buckets.rst (100%) create mode 120000 storage/docs/changelog.md create mode 100644 storage/docs/client.rst create mode 100644 storage/docs/conf.py create mode 100644 storage/docs/index.rst rename {docs/storage => storage/docs}/snippets.py (100%) diff --git a/docs/index.rst b/docs/index.rst index 0cb86cb4f815..58f03cfabb35 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -28,7 +28,7 @@ monitoring/index logging/usage redis/index - storage/client + storage/index tasks/index texttospeech/index translate/usage diff --git a/docs/storage b/docs/storage new file mode 120000 index 000000000000..de74c3c4f7cf --- /dev/null +++ b/docs/storage @@ -0,0 +1 @@ +../storage/docs/ \ No newline at end of file diff --git a/docs/storage/changelog.md b/docs/storage/changelog.md deleted file mode 120000 index 222f4f787a4e..000000000000 --- a/docs/storage/changelog.md +++ /dev/null @@ -1 +0,0 @@ -../../storage/CHANGELOG.md \ No newline at end of file diff --git a/docs/storage/client.rst b/docs/storage/client.rst deleted file mode 100644 index 0e52689a87bc..000000000000 --- a/docs/storage/client.rst +++ /dev/null @@ -1,37 +0,0 @@ -Storage -======= - -.. toctree:: - :maxdepth: 2 - :hidden: - - blobs - buckets - acl - batch - changelog - -Installation ------------- - -Install the ``google-cloud-storage`` library using ``pip``: - -.. code-block:: console - - $ pip install google-cloud-storage - -Usage ------ - -.. note:: - - Becuase the :class:`~google.cloud.storage.client.Client` uses the - third-party :mod:`requests` library by default, it is safe to - share instances across threads. In multiprocessing scenarious, best - practice is to create client instances *after* - :class:`multiprocessing.Pool` or :class:`multiprocessing.Process` invokes - :func:`os.fork`. - -.. automodule:: google.cloud.storage.client - :members: - :show-inheritance: diff --git a/storage/README.rst b/storage/README.rst index 9c7885dd7e8c..71cecf4c91cd 100644 --- a/storage/README.rst +++ b/storage/README.rst @@ -1,55 +1,77 @@ Python Client for Google Cloud Storage ====================================== - Python idiomatic client for `Google Cloud Storage`_ - -.. _Google Cloud Storage: https://cloud.google.com/storage/docs - |pypi| |versions| -- `Documentation`_ +`Google Cloud Storage`_ () allows you to store data on +Google infrastructure with very high reliability, performance and +availability, and can be used to distribute large data objects to users +via direct download. -.. _Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/storage/client.html +- `Client Library Documentation`_ +- `Storage API docs`_ + +.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-storage.svg + :target: https://pypi.org/project/google-cloud-storage +.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-storage.svg + :target: https://pypi.org/project/google-cloud-storage +.. _Google Cloud Storage: https://cloud.google.com/storage/docs +.. _Client Library Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/storage/client.html +.. _Storage API docs: https://cloud.google.com/storage/docs/json_api/v1 Quick Start ----------- -.. code-block:: console +In order to use this library, you first need to go through the following steps: - $ pip install --upgrade google-cloud-storage +1. `Select or create a Cloud Platform project.`_ +2. `Enable billing for your project.`_ +3. `Enable the Google Cloud Storage API.`_ +4. `Setup Authentication.`_ -For more information on setting up your Python development environment, -such as installing ``pip`` and ``virtualenv`` on your system, please refer -to `Python Development Environment Setup Guide`_ for Google Cloud Platform. +.. _Select or create a Cloud Platform project.: https://console.cloud.google.com/project +.. _Enable billing for your project.: https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project +.. _Enable the Google Cloud Storage API.: https://cloud.google.com/storage +.. _Setup Authentication.: https://googlecloudplatform.github.io/google-cloud-python/latest/core/auth.html -.. _Python Development Environment Setup Guide: https://cloud.google.com/python/setup +Installation +~~~~~~~~~~~~ -Authentication --------------- +Install this library in a `virtualenv`_ using pip. `virtualenv`_ is a tool to +create isolated Python environments. The basic problem it addresses is one of +dependencies and versions, and indirectly permissions. -With ``google-cloud-python`` we try to make authentication as painless as -possible. Check out the `Authentication section`_ in our documentation to -learn more. You may also find the `authentication document`_ shared by all -the ``google-cloud-*`` libraries to be helpful. +With `virtualenv`_, it's possible to install this library without needing system +install permissions, and without clashing with the installed system +dependencies. -.. _Authentication section: https://google-cloud-python.readthedocs.io/en/latest/core/auth.html -.. _authentication document: https://github.com/GoogleCloudPlatform/google-cloud-common/tree/master/authentication +.. _`virtualenv`: https://virtualenv.pypa.io/en/latest/ -Using the API -------------- -Google `Cloud Storage`_ (`Storage API docs`_) allows you to store data on -Google infrastructure with very high reliability, performance and -availability, and can be used to distribute large data objects to users -via direct download. +Mac/Linux +^^^^^^^^^ -.. _Cloud Storage: https://cloud.google.com/storage/docs -.. _Storage API docs: https://cloud.google.com/storage/docs/json_api/v1 +.. code-block:: console -See the ``google-cloud-python`` API `storage documentation`_ to learn how to -connect to Cloud Storage using this Client Library. + pip install virtualenv + virtualenv + source /bin/activate + /bin/pip install google-cloud-storage + + +Windows +^^^^^^^ + +.. code-block:: console -.. _storage documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/storage/client.html + pip install virtualenv + virtualenv + \Scripts\activate + \Scripts\pip.exe install google-cloud-storage + + +Example Usage +~~~~~~~~~~~~~ You need to create a Google Cloud Storage bucket to use this client library. Follow along with the `official Google Cloud Storage documentation`_ to learn @@ -69,8 +91,3 @@ how to create a bucket. blob.upload_from_string('New contents!') blob2 = bucket.blob('remote/path/storage.txt') blob2.upload_from_filename(filename='/local/path.txt') - -.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-storage.svg - :target: https://pypi.org/project/google-cloud-storage -.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-storage.svg - :target: https://pypi.org/project/google-cloud-storage diff --git a/docs/storage/acl.rst b/storage/docs/acl.rst similarity index 100% rename from docs/storage/acl.rst rename to storage/docs/acl.rst diff --git a/docs/storage/batch.rst b/storage/docs/batch.rst similarity index 100% rename from docs/storage/batch.rst rename to storage/docs/batch.rst diff --git a/docs/storage/blobs.rst b/storage/docs/blobs.rst similarity index 100% rename from docs/storage/blobs.rst rename to storage/docs/blobs.rst diff --git a/docs/storage/buckets.rst b/storage/docs/buckets.rst similarity index 100% rename from docs/storage/buckets.rst rename to storage/docs/buckets.rst diff --git a/storage/docs/changelog.md b/storage/docs/changelog.md new file mode 120000 index 000000000000..04c99a55caae --- /dev/null +++ b/storage/docs/changelog.md @@ -0,0 +1 @@ +../CHANGELOG.md \ No newline at end of file diff --git a/storage/docs/client.rst b/storage/docs/client.rst new file mode 100644 index 000000000000..54f094dea9be --- /dev/null +++ b/storage/docs/client.rst @@ -0,0 +1,6 @@ +Storage Client +~~~~~~~~~~~~~~ + +.. automodule:: google.cloud.storage.client + :members: + :show-inheritance: diff --git a/storage/docs/conf.py b/storage/docs/conf.py new file mode 100644 index 000000000000..907aba8007a5 --- /dev/null +++ b/storage/docs/conf.py @@ -0,0 +1,317 @@ +# -*- coding: utf-8 -*- +# +# google-cloud-storage documentation build configuration file +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os +import shlex + +# 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. +sys.path.insert(0, os.path.abspath('..')) + +__version__ = '0.90.4' + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# 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.ext.doctest', + 'sphinx.ext.intersphinx', + 'sphinx.ext.coverage', + 'sphinx.ext.napoleon', + 'sphinx.ext.viewcode', +] + +# autodoc/autosummary flags +autoclass_content = 'both' +autodoc_default_flags = ['members'] +autosummary_generate = True + +# 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' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'google-cloud-storage' +copyright = u'2017, Google' +author = u'Google APIs' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The full version, including alpha/beta/rc tags. +release = __version__ +# The short X.Y version. +version = '.'.join(release.split('.')[0:2]) + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + +# -- 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 = '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 = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# 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 = [] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' +#html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# Now only 'ja' uses this config value +#html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +#html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'google-cloud-storage-doc' + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + #'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + #'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + #'preamble': '', + + # Latex figure (float) alignment + #'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'google-cloud-storage.tex', + u'google-cloud-storage Documentation', author, 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [(master_doc, 'google-cloud-storage', + u'google-cloud-storage Documentation', [author], 1)] + +# If true, show URL addresses after external links. +#man_show_urls = False + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'google-cloud-storage', + u'google-cloud-storage Documentation', author, 'google-cloud-storage', + 'GAPIC library for the {metadata.shortName} v1 service', 'APIs'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = { + 'python': ('http://python.readthedocs.org/en/latest/', None), + 'gax': ('https://gax-python.readthedocs.org/en/latest/', None), +} + +# Napoleon settings +napoleon_google_docstring = True +napoleon_numpy_docstring = True +napoleon_include_private_with_doc = False +napoleon_include_special_with_doc = True +napoleon_use_admonition_for_examples = False +napoleon_use_admonition_for_notes = False +napoleon_use_admonition_for_references = False +napoleon_use_ivar = False +napoleon_use_param = True +napoleon_use_rtype = True diff --git a/storage/docs/index.rst b/storage/docs/index.rst new file mode 100644 index 000000000000..a9c7525fd1da --- /dev/null +++ b/storage/docs/index.rst @@ -0,0 +1,21 @@ +.. include:: /../storage/README.rst + +.. note:: + + Becuase the storage client uses the third-party :mod:`requests` library by + default, it is safe to share instances across threads. In multiprocessing + scenarious, best practice is to create client instances *after* + :class:`multiprocessing.Pool` or :class:`multiprocessing.Process` invokes + :func:`os.fork`. + +API Reference +------------- +.. toctree:: + :maxdepth: 2 + + client + blobs + buckets + acl + batch + changelog diff --git a/docs/storage/snippets.py b/storage/docs/snippets.py similarity index 100% rename from docs/storage/snippets.py rename to storage/docs/snippets.py