From 2cfccb0a7fb55ceec4c0b479c0b2bb72f37afc71 Mon Sep 17 00:00:00 2001 From: Tres Seaver Date: Wed, 12 Sep 2018 16:06:06 -0400 Subject: [PATCH] Prep translate docs for repo split. (#5941) - Move docs from 'docs/translate' into 'translate/docs' and leave symlink. - Harmonize / DRY 'translate/README.rst' and 'translate/docs/index.rst'. - Ensure that docs still build from top-level. Toward #5912. --- docs/index.rst | 2 +- docs/translate | 1 + docs/translate/usage.rst | 157 --------- translate/README.rst | 120 +++++-- .../translate => translate/docs}/changelog.md | 0 {docs/translate => translate/docs}/client.rst | 0 translate/docs/conf.py | 317 ++++++++++++++++++ translate/docs/index.rst | 26 ++ translate/docs/usage.rst | 110 ++++++ 9 files changed, 544 insertions(+), 189 deletions(-) create mode 120000 docs/translate delete mode 100644 docs/translate/usage.rst rename {docs/translate => translate/docs}/changelog.md (100%) rename {docs/translate => translate/docs}/client.rst (100%) create mode 100644 translate/docs/conf.py create mode 100644 translate/docs/index.rst create mode 100644 translate/docs/usage.rst diff --git a/docs/index.rst b/docs/index.rst index 44e34fa54f5e..490b7583524f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -31,7 +31,7 @@ storage/index tasks/index texttospeech/index - translate/usage + translate/index vision/index videointelligence/index websecurityscanner/index diff --git a/docs/translate b/docs/translate new file mode 120000 index 000000000000..8ce8fe7bf496 --- /dev/null +++ b/docs/translate @@ -0,0 +1 @@ +../translate/docs \ No newline at end of file diff --git a/docs/translate/usage.rst b/docs/translate/usage.rst deleted file mode 100644 index fd86fb9c8e9d..000000000000 --- a/docs/translate/usage.rst +++ /dev/null @@ -1,157 +0,0 @@ -Translation -=========== - -.. toctree:: - :maxdepth: 2 - :hidden: - - client - -With `Google Cloud Translation`_, you can dynamically translate text -between thousands of language pairs. The Google Cloud Translation API -lets websites and programs integrate with Google Cloud Translation -programmatically. Google Cloud Translation is available as a -paid service. See the `Pricing`_ and `FAQ`_ pages for details. - -Installation ------------- - -Install the ``google-cloud-translate`` library using ``pip``: - -.. code-block:: console - - $ pip install google-cloud-translate - -Authentication / Configuration ------------------------------- - -- Use :class:`~google.cloud.translate.client.Client` objects to configure - your applications. - -- :class:`~google.cloud.translate.client.Client` objects hold - a connection to the Cloud Translation service. - -Methods -------- - -To create a client: - - .. code:: - - >>> from google.cloud import translate - >>> client = translate.Client() - -By default, the client targets English when doing detections -and translations, but a non-default value can be used as -well: - - .. code:: - - >>> from google.cloud import translate - >>> client = translate.Client(target_language='es') - -The Google Cloud Translation API has three supported methods, and they -map to three methods on a client: -:meth:`~google.cloud.translate.client.Client.get_languages`, -:meth:`~google.cloud.translate.client.Client.detect_language` and -:meth:`~google.cloud.translate.client.Client.translate`. - -To get a list of languages supported by the Google Cloud Translation API - - .. code:: - - >>> from google.cloud import translate - >>> client = translate.Client() - >>> client.get_languages() - [ - { - 'language': 'af', - 'name': 'Afrikaans', - }, - ... - ] - -To detect the language that some given text is written in: - - .. code:: - - >>> from google.cloud import translate - >>> client = translate.Client() - >>> client.detect_language(['Me llamo', 'I am']) - [ - { - 'confidence': 0.25830904, - 'input': 'Me llamo', - 'language': 'es', - }, { - 'confidence': 0.17112699, - 'input': 'I am', - 'language': 'en', - }, - ] - -The `confidence`_ value is an optional floating point value between 0 and 1. -The closer this value is to 1, the higher the confidence level for the -language detection. This member is not always available. - -To translate text into the default destination language without knowing -the source language: - - .. code:: - - >>> from google.cloud import translate - >>> client = translate.Client() - >>> client.translate('koszula') - { - 'translatedText': 'shirt', - 'detectedSourceLanguage': 'pl', - 'input': 'koszula', - } - -If the source language is known: - - .. code:: - - >>> from google.cloud import translate - >>> client = translate.Client() - >>> client.translate('camisa', source_language='es') - { - 'translatedText': 'shirt', - 'input': 'camisa', - } - -or to use a non-default target language: - - .. code:: - - >>> from google.cloud import translate - >>> client = translate.Client() - >>> client.translate(['Me llamo Jeff', 'My name is Jeff'], - ... target_language='de') - [ - { - 'translatedText': 'Mein Name ist Jeff', - 'detectedSourceLanguage': 'es', - 'input': 'Me llamo Jeff', - }, { - 'translatedText': 'Mein Name ist Jeff', - 'detectedSourceLanguage': 'en', - 'input': 'My name is Jeff', - }, - ] - -.. _Google Cloud Translation: https://cloud.google.com/translate/ -.. _Pricing: https://cloud.google.com/translate/pricing -.. _FAQ: https://cloud.google.com/translate/faq -.. _Identifying your application to Google: https://cloud.google.com/translate/docs/translating-text -.. _confidence: https://cloud.google.com/translate/docs/detecting-language - -Changelog ---------- - -For a list of all ``google-cloud-translate`` releases: - -.. toctree:: - :maxdepth: 2 - - changelog diff --git a/translate/README.rst b/translate/README.rst index b9a7a23f977f..e5de25d152cc 100644 --- a/translate/README.rst +++ b/translate/README.rst @@ -1,53 +1,111 @@ Python Client for Google Cloud Translation ========================================== - Python idiomatic client for `Google Cloud Translation`_ +|pypi| |versions| -.. _Google Cloud Translation: https://cloud.google.com/translate/ +With `Google Cloud Translation`_, you can dynamically translate text between +thousands of language pairs. The Google Cloud Translation API lets websites +and programs integrate with Google Cloud Translation programmatically. Google +Cloud Translation is available as a paid service. See the `Pricing`_ and +`FAQ`_ pages for details. -|pypi| |versions| +- `Client Library Documentation`_ +- `Product Documentation`_ -- `Documentation`_ -.. _Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/translate/usage.html +.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-translate.svg + :target: https://pypi.org/project/google-cloud-translate/ +.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-translate.svg + :target: https://pypi.org/project/google-cloud-translate/ +.. _Google Cloud Translation: https://cloud.google.com/translate/ +.. _Pricing: https://cloud.google.com/translate/pricing +.. _FAQ: https://cloud.google.com/translate/faq +.. _Client Library Documentation: https://googlecloudplatform.github.io/google-cloud-python/latest/translate/usage.html +.. _Product Documentation: https://cloud.google.com/translate/docs 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-translate +1. `Select or create a Cloud Platform project.`_ +2. `Enable billing for your project.`_ +3. `Enable the Google Cloud Datastore 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 Datastore API.: https://cloud.google.com/datastore +.. _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 -------------- -With the Google Cloud `Translation`_ API (`Translation API docs`_), you can -dynamically translate text between thousands of language pairs. +Mac/Linux +^^^^^^^^^ -.. _Translation: https://cloud.google.com/translate/ -.. _Translation API docs: https://cloud.google.com/translate/docs/apis +.. code-block:: console -See the ``google-cloud-python`` API Translation `Documentation`_ to learn -how to translate text using this library. + pip install virtualenv + virtualenv + source /bin/activate + /bin/pip install google-cloud-datastore -.. |pypi| image:: https://img.shields.io/pypi/v/google-cloud-translate.svg - :target: https://pypi.org/project/google-cloud-translate/ -.. |versions| image:: https://img.shields.io/pypi/pyversions/google-cloud-translate.svg - :target: https://pypi.org/project/google-cloud-translate/ + +Windows +^^^^^^^ + +.. code-block:: console + + pip install virtualenv + virtualenv + \Scripts\activate + \Scripts\pip.exe install google-cloud-datastore + + +Example Usage +~~~~~~~~~~~~~ + +.. code-block:: python + + >>> from google.cloud import translate + >>> client = translate.Client() + >>> client.get_languages() + [ + { + 'language': 'af', + 'name': 'Afrikaans', + }, + ... + ] + >>> client.detect_language(['Me llamo', 'I am']) + [ + { + 'confidence': 0.25830904, + 'input': 'Me llamo', + 'language': 'es', + }, { + 'confidence': 0.17112699, + 'input': 'I am', + 'language': 'en', + }, + ] + >>> from google.cloud import translate + >>> client = translate.Client() + >>> client.translate('koszula') + { + 'translatedText': 'shirt', + 'detectedSourceLanguage': 'pl', + 'input': 'koszula', + } diff --git a/docs/translate/changelog.md b/translate/docs/changelog.md similarity index 100% rename from docs/translate/changelog.md rename to translate/docs/changelog.md diff --git a/docs/translate/client.rst b/translate/docs/client.rst similarity index 100% rename from docs/translate/client.rst rename to translate/docs/client.rst diff --git a/translate/docs/conf.py b/translate/docs/conf.py new file mode 100644 index 000000000000..d3fbd9681138 --- /dev/null +++ b/translate/docs/conf.py @@ -0,0 +1,317 @@ +# -*- coding: utf-8 -*- +# +# google-cloud-translate 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-translate' +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-translate-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-translate.tex', + u'google-cloud-translate 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-translate', + u'google-cloud-translate 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-translate', + u'google-cloud-translate Documentation', author, 'google-cloud-translate', + '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/translate/docs/index.rst b/translate/docs/index.rst new file mode 100644 index 000000000000..ba85ec9fe05f --- /dev/null +++ b/translate/docs/index.rst @@ -0,0 +1,26 @@ +.. include:: /../translate/README.rst + +Detailed Usage Guide +-------------------- +.. toctree:: + :maxdepth: 2 + + usage + +API Reference +------------- +.. toctree:: + :maxdepth: 2 + + client + +Changelog +--------- + +For a list of all ``google-cloud-translate`` releases: + +.. toctree:: + :maxdepth: 2 + + changelog + diff --git a/translate/docs/usage.rst b/translate/docs/usage.rst new file mode 100644 index 000000000000..5fc2767c06e6 --- /dev/null +++ b/translate/docs/usage.rst @@ -0,0 +1,110 @@ +Using the Translate Client +-------------------------- + +To create a client: + +.. doctest:: + + >>> from google.cloud import translate + >>> client = translate.Client() + +By default, the client targets English when doing detections +and translations, but a non-default value can be used as +well: + +.. doctest:: + + >>> from google.cloud import translate + >>> client = translate.Client(target_language='es') + +The Google Cloud Translation API has three supported methods, and they +map to three methods on a client: +:meth:`~google.cloud.translate.client.Client.get_languages`, +:meth:`~google.cloud.translate.client.Client.detect_language` and +:meth:`~google.cloud.translate.client.Client.translate`. + +To get a list of languages supported by the Google Cloud Translation API + +.. doctest:: + + >>> from google.cloud import translate + >>> client = translate.Client() + >>> client.get_languages() + [ + { + 'language': 'af', + 'name': 'Afrikaans', + }, + ... + ] + +To detect the language that some given text is written in: + +.. doctest:: + + >>> from google.cloud import translate + >>> client = translate.Client() + >>> client.detect_language(['Me llamo', 'I am']) + [ + { + 'confidence': 0.25830904, + 'input': 'Me llamo', + 'language': 'es', + }, { + 'confidence': 0.17112699, + 'input': 'I am', + 'language': 'en', + }, + ] + +The `confidence`_ value is an optional floating point value between 0 and 1. +The closer this value is to 1, the higher the confidence level for the +language detection. This member is not always available. + +.. _confidence: https://cloud.google.com/translate/docs/detecting-language + +To translate text into the default destination language without knowing +the source language: + +.. doctest:: + + >>> from google.cloud import translate + >>> client = translate.Client() + >>> client.translate('koszula') + { + 'translatedText': 'shirt', + 'detectedSourceLanguage': 'pl', + 'input': 'koszula', + } + +If the source language is known: + +.. doctest:: + + >>> from google.cloud import translate + >>> client = translate.Client() + >>> client.translate('camisa', source_language='es') + { + 'translatedText': 'shirt', + 'input': 'camisa', + } + +or to use a non-default target language: + +.. doctest:: + + >>> from google.cloud import translate + >>> client = translate.Client() + >>> client.translate(['Me llamo Jeff', 'My name is Jeff'], + ... target_language='de') + [ + { + 'translatedText': 'Mein Name ist Jeff', + 'detectedSourceLanguage': 'es', + 'input': 'Me llamo Jeff', + }, { + 'translatedText': 'Mein Name ist Jeff', + 'detectedSourceLanguage': 'en', + 'input': 'My name is Jeff', + }, + ]