From e11b31da13e050eeb7b0c7e24963b5abf8809a43 Mon Sep 17 00:00:00 2001 From: Luke Sneeringer Date: Fri, 22 Dec 2017 14:07:56 -0800 Subject: [PATCH] Artman documentation (#355) --- .circleci/config.yml | 22 ++- README.rst | 164 ++++-------------- docs/_static/custom.css | 16 ++ docs/_static/images/favicon.ico | Bin 0 -> 8348 bytes docs/conf.py | 299 ++++++++++++++++++++++++++++++++ docs/getting-started.rst | 47 +++++ docs/index.rst | 34 ++++ docs/installing.rst | 84 +++++++++ docs/support.rst | 39 +++++ nox.py | 18 ++ 10 files changed, 586 insertions(+), 137 deletions(-) create mode 100644 docs/_static/custom.css create mode 100644 docs/_static/images/favicon.ico create mode 100644 docs/conf.py create mode 100644 docs/getting-started.rst create mode 100644 docs/index.rst create mode 100644 docs/installing.rst create mode 100644 docs/support.rst diff --git a/.circleci/config.yml b/.circleci/config.yml index 57b5827c..333902ed 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -1,15 +1,6 @@ --- version: 2.0 jobs: - build: - docker: - - image: python:3.6 - steps: - - run: - name: Hello world! - command: echo "Hello world!" - working_directory: /usr/src/artman/ - build_and_push_docker_image: working_directory: /usr/src/artman docker: @@ -79,6 +70,18 @@ jobs: - store_artifacts: path: /artman/test/golden/actual_library_example.golden + docs: + docker: + - image: python:3.6 + steps: + - checkout + - run: + name: Install nox. + command: pip install --upgrade nox-automation + - run: + name: Build the docs. + command: nox -e docs + unit-python2.7: docker: - image: python:2.7 @@ -304,6 +307,7 @@ workflows: - unit-python3.4 - unit-python3.5 - unit-python3.6 + - docs - smoke-csharp - smoke-go - smoke-java diff --git a/README.rst b/README.rst index 644b280c..ea0817e6 100644 --- a/README.rst +++ b/README.rst @@ -1,140 +1,48 @@ Google API Artifact Manager =========================== -Google API Artifact manager (artman) is a set of modules used to automate the -creation of software artifacts related to APIS defined using `protobuf`_ IDL. - -artman is an extensible framework that is responsible for creating all artifacts -related to an API including - -- distribution packages in all supported programming languages -- generic documentation websites -- language-specific documentation websites (javadoc, readthedocs, etc) - -from the protobuf source IDL and additional configuration in YAML files. - -.. _`protobuf`: https://github.com/google/protobuf - - -Installation ------------- -1. Optional: set up a virtualenv for your Python work. Choose one of - the following: - - 1. (recommended) `virtualenvwrapper`_ so you don't have to keep - track of where your virtualenv is on the filesystem: - - .. code:: - - sudo pip install virtualenv virtualenvwrapper - mkvirtualenv --python=`which python3` artman - - To use this virtual environment later: - - .. code :: - - workon artman - - 2. `virtualenv`_ in your current directory: - - .. code:: - - sudo pip install virtualenv - virtualenv env - source env/bin/activate - -2. Install artman directly from pip: - - .. code:: - - pip install googleapis-artman - -You may need root privileges if you are not installing inside of a virtualenv. -This will make the ``artman`` command available on your system. - -.. _`virtualenvwrapper`: https://virtualenvwrapper.readthedocs.io/en/latest/ -.. _`virtualenv`: https://pypi.python.org/pypi/virtualenv - - -Prerequisites -------------- -1. Install `googleapis`_ -2. Install `toolkit`_ -3. Install Java -4. Some languages may have additional dependencies; refer to the ``Dockerfile`` - in this repository for canonical installation requirements. - -.. _`googleapis`: https://github.com/googleapis/googleapis +Google API Artifact Manager (``artman``) is a program used to automate the +generaton and publishing of API client libraries. + +In order to be consumed by artman, APIs require: + + * A `Protocol Buffers`_ description of the API, specified using proto3 + syntax. + * A `service configuration`_ stub. This is YAML configuration which + designates how the API is housed within Google's infrastructure. + * A GAPIC configuration. This provides extra information specific to + generating a client library. + * An artman configuration. This is the file artman uses as the entry point, + and it points to the previous items in this list. + +The artman tool is a wrapper around `toolkit`_; it takes the configuration +enumerated above, normalizes it, and sends it to toolkit, which generates +a client library on disk, and then artman performs some concluding cleanup. + +Client libraries produced in this way are executable "out of the box", and +include basic reference documentation, and appropriate packaging and +metadata files. + +.. _`Protocol Buffers`: https://developers.google.com/protocol-buffers/ +.. _`service configuration`: https://cloud.google.com/service-management/overview#service_configurations .. _`toolkit`: https://github.com/googleapis/toolkit -Usage ------ - -Before you can use artman, you will need a configuration file. You can run -``configure-artman`` to create a simple configuration file. - -For building a GAPIC (the most common task), the usage looks like: - -.. code:: - - artman --api pubsub --language python - -Artman also takes a ``--publish`` argument to decide where to stage the -code. Using ``--publish github`` will create a pull request on GitHub -automatically. - - -Python Versions ---------------- - -artman is currently tested with Python 2.7, Python 3.4, Python 3.5, -and Python 3.6. - -.. note:: - - The authors of this README are humans, and this is an exceptionally - easy spot to end up out of date. - - Our ``nox.py`` and ``.circleci/config.yml`` files are the real source - of truth for what versions of Python we test against. - - -Contributing ------------- - -Contributions to this library are always welcome and highly encouraged. - -See the `CONTRIBUTING`_ documentation for more information on how to get -started. - -.. _`CONTRIBUTING`: https://github.com/googleapis/artman/blob/master/CONTRIBUTING.rst - - -Versioning ----------- - -This library follows `Semantic Versioning`_ - -It is currently in major version zero (``0.y.z``), which means that anything -may change at any time and the public API should not be considered -stable. - -.. _`Semantic Versioning`: http://semver.org/ - - -Details -------- +Installing +========== -For detailed documentation of the modules in artman, please watch -`DOCUMENTATION`_. +If your goal is just to use ``artman`` (rather than contribute to it), a +standard pip install is probably not the right thing; we recommend +the use of `pipsi`_ instead. -.. _`DOCUMENTATION`: https://googleapis-artman.readthedocs.org/ +View our `installation guide`_ to get going. +.. _`pipsi`: https://github.com/mitsuhiko/pipsi +.. _`installation guide`: https://googleapis-artman.readthedocs.io/latest/installing.html -License -------- +Documentation +============= -BSD - See `LICENSE`_ for more information. +Documentation is available on `Read the Docs`_. -.. _`LICENSE`: https://github.com/googleapis/artman/blob/master/LICENSE +.. _`Read the Docs`: https://googleapis-artman.readthedocs.io/ diff --git a/docs/_static/custom.css b/docs/_static/custom.css new file mode 100644 index 00000000..3d0319dd --- /dev/null +++ b/docs/_static/custom.css @@ -0,0 +1,16 @@ +@import url('https://fonts.googleapis.com/css?family=Roboto|Roboto+Mono'); + +@media screen and (min-width: 1080px) { + div.document { + width: 1040px; + } +} + +code.descname { + color: #4885ed; +} + +th.field-name { + min-width: 100px; + color: #3cba54; +} diff --git a/docs/_static/images/favicon.ico b/docs/_static/images/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..23c553a2966ca4cecf146093f33d8114b4f1e368 GIT binary patch literal 8348 zcmeI0du&tJ8Ng3Vwv|ewX4Hu@my&|vCD%DN@CLnxyptBT_%HjatoYr7%N3zGPed#@ckvA><;HWecDU4&2}*2(h%gm&WgCftWj zkQfW;&mXr@0S&(csd+cjaImbXSy=NC<10}z(efGwgi=;B$dt=HkKYCvp-#3KX+qIu zxx$>zcwk+N=c%1^J9)sO44lmS0##~wzU(43f>wW-p_YXwj>s>3{gHI*^oo1lmJ!X*bw{3UBAKRut zUh5Uy4_94IIkdxC^v{_g%FjuEI+f&;9KQ3i+nK7pU_RivFjP_DTl-&gP_qr$nD=M{ z@z;C3#y5Jsh77svGQ4u$ZX)t}=e52{#Xvk;4qIxNh86kR$OhCAie%&e`U{r{ACQZ@ z-)1#sItef{2L za&U;nm+_lo@lbR7vat&^EcECsH)uSnhlht@etsV4LE5B`j#GW*iur~}xpYlTtc;FC{nl|LK^miZ0y3WU>MIM zmc}94VzEFx9?#&?4l+h;ggzvOeCI$ob=`tBp*&EtirH2xU z4a#KB)IMa{_YdYrnxq>-DrrQ>rfpYe8@|Nc-oHnG*L(HR$}d4Eo2&X@o1~9l@%@W) zU{%rv$`tBAOHJH+?zcv7`!T~x;=<#7@4R5T^5$-%Pz-NAYt+5{d;>R+9W24y&`;ZkZqFGQ6_)<35Z_$5V#ga#=N9985-M0KR*fl@h4M0BxWvbYQr6t zULtYBAMJ%iU>x|?U8z_Zyv1jg_VcZ^kO)pd_)jk`_~2MHZmybbloW?l)lnMrb~TAX zV&%#e+VLvM4!%js+%B6}N!=udFlN5Jv;yQm0sdW({6ny+{{$_b`%pI&q3%#p3R?q( z%3@zpafPo4-GA}ErIfU@j?gpfdgeyI);;S-otz(GefQbXvG3J6hbwD_0*YOuqb1V8 zpQm{(oT|g$!tcw;Ck6l>=mo$z0J@0f0^U0{x?+mD8}QB{9yV7qQ;&$5^%*fb@qUB& zX(O<{D-aZ493K;1xH%!}9+}vt8Sshs4os9)d132glTa=lIJv}MJyU_Y!ZFl62j9@l zggg2y{y~c&Vm0cMa@}r@bbn?HR4Sa|66p;nlMl_6D%_%EjCNRq)NBvx!R!t`@zUoW zKV#O#EhZy4>~?VU+rfg@_W_4Kt~zS<|3JjVMcZ#exy;pDUypq|xjpD&0#H{BHgrvM zI=z9nnTN~NCX?mf@DOU;!82-#gXGsw5CSSf22lJ>u8duE&igGuZq4lVZf*LH2%QqOqkv@O{w`Y}q~yWm0EP zeSP~Hau49ZBU@&hWwH5YG0dnGVN1^iztQFh>rIvj5$iQ;q^nyuSuXo`U~{E8DpuIS zA{kR5oC9o=_>jhfRX@QTs1KRm{@F31 zFKP1!w?51@R^I~kA%H*B0W^sKnyVIsv`_2;=zbUGR9pOTqUhV{{^UH=RQ2@S?`uaQ zEy`)Gsd}1IEedW&4lAe0Sg5h`nQXqaZ}RyEzX{FT?hmF3>0_QQT1V~jI$wc&1@aZh ZS0G=3d706zJ{{SaIO|Jj| literal 0 HcmV?d00001 diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..85750a73 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,299 @@ +# Copyright 2016 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +# google-cloud documentation build configuration file, created by +# sphinx-quickstart on Tue Jan 21 22:24:47 2014. +# +# 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 email +import os +import pkg_resources + +# 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('..')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +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 ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', + 'sphinx.ext.napoleon', + 'sphinx.ext.todo', + 'sphinx.ext.viewcode', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = [] + +# The suffix of source filenames. +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'googleapis-artman' +copyright = u'2016-2018 Google LLC' + +# 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 short X.Y version. +distro = pkg_resources.get_distribution('googleapis-artman') +release = os.getenv('SPHINX_RELEASE', distro.version) + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#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 = [] + + +# -- 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 = { + 'description': 'Google API Artifact Manager', + 'github_user': 'googleapis', + 'github_repo': 'artman', + '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 = [] + +# 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 = '_static/images/favicon.ico' + +# 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'] + +html_add_permalinks = '#' + +# 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 = { + '**': [ + 'about.html', + 'navigation.html', + 'relations.html', + 'searchbox.html', + ] +} + +# 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 + +# Output file base name for HTML help builder. +htmlhelp_basename = 'google-cloud-doc' + +html_context = {} + + +# -- 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': '', +} + +metadata = distro.get_metadata(distro.PKG_INFO) +author = email.message_from_string(metadata).get('Author') +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'google-cloud.tex', u'google-cloud 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 warnings ------------------------------------------------------ + + +suppress_warnings = [] + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'google-cloud', u'google-cloud 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 = [ + ('index', 'googleapis-artman', u'googleapis-artman Documentation', + author, 'googleapis-artman', 'Google APIs Artifact Manager.', + 'Miscellaneous'), +] + +# 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' + +# This pulls class descriptions from the class docstring, +# and parameter definitions from the __init__ docstring. +autoclass_content = 'both' + +# Configuration for intersphinx: +intersphinx_mapping = { + 'python': ('https://docs.python.org/3', None), +} diff --git a/docs/getting-started.rst b/docs/getting-started.rst new file mode 100644 index 00000000..433458fe --- /dev/null +++ b/docs/getting-started.rst @@ -0,0 +1,47 @@ +Getting Started +=============== + +It is time to build a client library! + +Using ``artman`` requires two concepts: (1) pointing to a artman configuration +file, which tells artman what source material it is working off of, and (2) +telling it what you want it to do. + +Here is an example command: + +.. code-block:: bash + + # Right now, artman is location-aware; you need to be in the + # googleapis directory for everything to work correctly. + $ cd /path/to/googleapis/ + + # Build the language.v1 API library, and produce a Python client. + $ artman --config google/cloud/language/artman_language_v1.yaml \ + generate python_gapic + +Unpacking that command: + + * The ``--config`` switch (which is actually required) tells artman what + inputs to use. In this case, the configuration is for the + `Natural Language API`_. + + .. note:: + + As of this writing, some artman YAML configs have a version at the + end, and some do not. (We are moving in the direction of + consistently having them.) + + * ``generate`` is the command / verb. (artman also supports ``publish``, + which is able to, for example, automatically create a pull request on + GitHub.) + + * ``python_gapic`` is the objective -- the thing you want to be produced. + You essentially always want a GAPIC (an old code name for the complete, + auto-generated API client), but seven languages are supported at this + time; ``ruby_gapic``, ``java_gapic``, etc. will give you what you expect. + +The package will be dropped in a newly created ``artman-genfiles/`` directory +within your current working directory; the output of the command will tell +you precisely where it put the library. + +.. _`Natural Language API`: https://cloud.google.com/natural-language/ diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..5ed4dc35 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,34 @@ +Google API Artifact Manager +=========================== + +Google API Artifact Manager (``artman``) is a program used to automate the +generation and publishing of API client libraries. + +In order to be consumed by artman, APIs require: + + * A `Protocol Buffers`_ description of the API, specified using proto3 + syntax. + * A `service configuration`_ stub. This is YAML configuration which + designates how the API is housed within Google's infrastructure. + * A GAPIC configuration. This provides extra information specific to + generating a client library. + * An artman configuration. This is the file artman uses as the entry point, + and it points to the previous items in this list. + +The artman tool is a wrapper around `toolkit`_; it takes the configuration +enumerated above, normalizes it, and sends it to toolkit, which generates +a client library on disk, and then artman performs some concluding cleanup. + +Client libraries produced in this way are executable "out of the box", and +include basic reference documentation, and appropriate packaging and +metadata files. + +.. _`Protocol Buffers`: https://developers.google.com/protocol-buffers/ +.. _`service configuration`: https://cloud.google.com/service-management/overview#service_configurations +.. _`toolkit`: https://github.com/googleapis/toolkit + + +.. toctree:: + installing + getting-started + support diff --git a/docs/installing.rst b/docs/installing.rst new file mode 100644 index 00000000..bc5320d3 --- /dev/null +++ b/docs/installing.rst @@ -0,0 +1,84 @@ +Installation +============ + +Prerequisites +------------- + +Docker +~~~~~~ +Because of the many, many things that must be on your system for artman to +do its job, artman utilizes `Docker`_ and ships a container which has +appropriate dependencies available. You will, therefore, need Docker to be +on your system. + +.. note:: + + It is also possible to run artman locally (use ``--local``) when invoking + it. This is generally only recommended for development of artman itself, + but is an option. If you do this, use our `Dockerfile`_ as a reference + to what dependencies you are likely to need. + +.. _`Docker`: https://docker.com/ +.. _`Dockerfile`: https://github.com/googleapis/artman/blob/master/Dockerfile + +googleapis +~~~~~~~~~~ +Currently, artman is primarily used for building Google Cloud client libraries, +and depends on a large, interdependent configuration structure. This is housed +in the `googleapis`_ repository. + +In order to run artman, you will need to clone this repository, and generally +you should be in this directory when invoking artman. + +.. code-block:: bash + + $ git clone git@github.com:googleapis/googleapis.git googleapis/ + + +Installation +------------ + +1. If you have not already, install `pip`_ and `virtualenv`_. + (Use ``which pip`` or ``which virtualenv`` to see if you already have them.) + +1. Install Armin Ronacher's `pipsi`_. This is a tool for installing scripts + on your machine without touching system Python and without having to worry + about the script's virutal environment. In other words, it is the correct + tool for exactly this problem. + + .. code-block:: bash + + # This instruction is from the pipsi README; if you have trouble, + # double-check there. + $ curl https://raw.githubusercontent.com/mitsuhiko/pipsi/master/get-pipsi.py | python + +1. Install artman itself: + + .. code-block:: bash + + $ pipsi install googleapis-artman + + This will place an executable spelled ``artman`` on your path. + If you need to upgrade artman in the future, you can use + ``pipsi upgrade googleapis-artman`` to do so. + +.. _`pip`: https://pip.pypa.io/en/stable/installing/ +.. _`pipsi`: https://github.com/mitsuhiko/pipsi +.. _`virtualenv`: https://virtualenv.pypa.io/en/stable/ + + +Configuration +------------- + +The artman tool requires some configuration in order to run (some of this +is legacy from before artman was primarily run in Docker). + +When you try to run ``artman`` the first time, it will complain and ask +for a configuration file. Run ``configure-artman`` which will interactively +walk you through the steps to create one, and then place it in the right spot. + +The configuration tool will ask you for a "repository root". You should +specify the directory *above* wherever you cloned googleapis to, and then +you can use the defaults for everything else it asks. + +This tool will be improved or removed in a future version. diff --git a/docs/support.rst b/docs/support.rst new file mode 100644 index 00000000..f0d4c4e2 --- /dev/null +++ b/docs/support.rst @@ -0,0 +1,39 @@ +Support +======= + +Python Versions +--------------- + +artman is currently tested with Python 2.7, Python 3.4, Python 3.5, +and Python 3.6. + +.. note:: + + The authors of this documentation are humans, and this is an exceptionally + easy spot to end up out of date. + + Our ``nox.py`` and ``.circleci/config.yml`` files are the real source + of truth for what versions of Python we test against. + + +Versioning +---------- + +This library follows `Semantic Versioning`_ + +It is currently in major version zero (``0.y.z``), which means that anything +may change at any time and the public API should not be considered +stable. + +.. _`Semantic Versioning`: http://semver.org/ + + +Contributing +------------ + +Contributions to this library are always welcome and highly encouraged. + +See the `CONTRIBUTING`_ documentation for more information on how to get +started. + +.. _`CONTRIBUTING`: https://github.com/googleapis/artman/blob/master/CONTRIBUTING.rst diff --git a/nox.py b/nox.py index 33379b8a..86e735e6 100644 --- a/nox.py +++ b/nox.py @@ -15,6 +15,7 @@ from __future__ import absolute_import import nox +import os @nox.session @@ -52,3 +53,20 @@ def coverage(session): session.run('coverage', 'html') finally: session.run('coverage', 'erase') + + +@nox.session +def docs(session): + """Build the docs.""" + + # Set the virtualenv dirname. + session.virtualenv_dirname = 'docs' + + # Install Sphinx and also all of the google-cloud-* packages. + session.chdir(os.path.realpath(os.path.dirname(__file__))) + session.install('setuptools >= 36.4.0', 'sphinx >= 1.6.3', '.') + + # Build the docs! + session.run('rm', '-rf', 'docs/_build/') + session.run('sphinx-build', '-W', '-b', 'html', '-d', + 'docs/_build/doctrees', 'docs/', 'docs/_build/html/')