From c8ddcac80202626f0a5eb6680744f7dc4a5aff96 Mon Sep 17 00:00:00 2001 From: Dov Shlachter Date: Tue, 13 Oct 2020 12:52:30 -0700 Subject: [PATCH] docs: remove references to pipsi Multiple people have experienced difficulty with pipsi. To that end, documentation recommending its use is now rewritten to recommend just using pyenv. Adds small comment expansion aroud bazel rules. --- docs/getting-started/index.rst | 10 ++++++++-- docs/getting-started/local.rst | 18 +++++++++++------- 2 files changed, 19 insertions(+), 9 deletions(-) diff --git a/docs/getting-started/index.rst b/docs/getting-started/index.rst index fa2ebf0223..ec9149a582 100644 --- a/docs/getting-started/index.rst +++ b/docs/getting-started/index.rst @@ -7,7 +7,8 @@ protocol buffers do. Because dependency management and such can be a significant undertaking, we offer a Docker image and interface which requires you only to have Docker -installed and provide the protos for your API. +installed and provide the protos for your API. Alternatively, the generator is +also invocable via bazel rules. It is also possible to install the tool locally and run it through ``protoc``, and this approach is fully supported. @@ -15,7 +16,12 @@ and this approach is fully supported. .. note:: The Docker approach is recommended for users new to this ecosystem, or - those which do not have a robust Python environment available. + those which do not have a robust Python environment available. If you want + to experiment with generating client libraries but do not want to make + changes to the generator itself, try the Docker image first. + + The bazel approach is recommended for established pipelines. It is more + lightweight than the Docker image but may take some more effort to set up. .. _protocol buffers: https://developers.google.com/protocol-buffers/ diff --git a/docs/getting-started/local.rst b/docs/getting-started/local.rst index 5251dccad8..9c2a989fb8 100644 --- a/docs/getting-started/local.rst +++ b/docs/getting-started/local.rst @@ -80,9 +80,6 @@ Python 3.7, so you will need that installed. (Most Linux distributions ship with earlier versions.) Use `pyenv`_ to get Python 3.7 installed in a friendly way. -As for this library itself, the recommended installation approach is -`pipsi`_. - .. code-block:: shell # Due to its experimental state, this tool is not published to a @@ -91,11 +88,19 @@ As for this library itself, the recommended installation approach is git clone https://github.com/googleapis/gapic-generator-python.git cd gapic-generator-python/ - # Install the tool. This will handle the virtualenv for you, and + # Install a version of python that is supported by the microgenerator. + # We use 3.8.6 as an example. + # You may need to install additional packages in order to + # build python from source. + # Setting a 'global' python is convenient for development but may interfere + # with other system activities. Adjust as your environment requires. + pyenv install 3.8.6 && pyenv global 3.8.6 + + # Install the tool. This will handle the virtualenv for you, and # make an appropriately-aliased executable. # The `--editable` flag is only necessary if you want to work on the # tool (as opposed to just use it). - pipsi install --editable --python=`which python3.7` . + python -m pip install --editable . To ensure the tool is installed properly: @@ -105,7 +110,6 @@ To ensure the tool is installed properly: /path/to/protoc-gen-python_gapic .. _pyenv: https://github.com/pyenv/pyenv -.. _pipsi: https://github.com/mitsuhiko/pipsi Usage ----- @@ -151,7 +155,7 @@ This plugin is invoked under the hood via. the ``--python_gapic_out`` switch. the common protos must come first, and then the path to the API being built. .. include:: _samplegen.rst - + .. code-block:: shell # Multiple sample paths or directories can be passed simultaneously by duplicating