docs: gRPC tutorial (#3013)

## What does this PR address?   This PR updates default tutorial with how to run BentoML with gRPC. Additionally, this PR update installation guides on how people can install and use BentoML. I ran across some links and fix that as well. I also migrate setup.cfg to pyproject.toml We introduce an `bentoml[extras]` that will install bentoml with all of the features (pydantic, s3 support, image io, pandas) at #3025 ## Before submitting:    - [ ] Does the Pull Request follow [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/#summary) naming? Here are [GitHub's guide](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) on how to create a pull request. - [ ] Does the code follow BentoML's code style, both `make format` and `make lint` script have passed ([instructions](https://github.com/bentoml/BentoML/blob/main/DEVELOPMENT.md#style-check-auto-formatting-type-checking))? - [ ] Did you read through [contribution guidelines](https://github.com/bentoml/BentoML/blob/main/CONTRIBUTING.md#ways-to-contribute) and follow [development guidelines](https://github.com/bentoml/BentoML/blob/main/DEVELOPMENT.md#start-developing)? - [ ] Did your changes require updates to the documentation? Have you updated those accordingly? Here are [documentation guidelines](https://github.com/bentoml/BentoML/tree/main/docs) and [tips on writting docs](https://github.com/bentoml/BentoML/tree/main/docs#writing-documentation). - [ ] Did you write tests to cover your changes? Signed-off-by: Aaron Pham <[email protected]> Co-authored-by: Sean Sheng <[email protected]> Co-authored-by: Sauyon Lee <[email protected]>
bentoml · Sep 27, 2022 · 7ddfca4 · 7ddfca4
1 parent 266b131
commit 7ddfca4
Show file tree

Hide file tree

Showing 7 changed files with 495 additions and 158 deletions.
diff --git a/bentoml/bentos.py b/bentoml/bentos.py
@@ -163,6 +163,12 @@ def export_bento(
     """
     Export a bento.
 
+    To export a bento to S3, you must install BentoML with extras ``aws``:
+
+    .. code-block:: bash
+
+       » pip install bentoml[aws]
+
     Examples:
 
     .. code-block:: python

diff --git a/docs/source/concepts/bento.rst b/docs/source/concepts/bento.rst
@@ -538,6 +538,60 @@ desired version, install from a custom PyPI source, or install from a GitHub rep
     can override this by specifying a different BentoML version.
 
 
+To use a variant of BentoML with additional features such as gRPC, tracing exporters, pydantic
+validation, specify the desired variant in the under ``python.packages`` field:
+
+.. tab-set::
+
+   .. tab-item:: gRPC
+
+      .. code-block:: yaml
+         python:
+            packages:
+            - "bentoml[grpc]"
+
+   .. tab-item:: AWS
+
+      .. code-block:: yaml
+          python:
+              packages:
+              - "bentoml[aws]"
+
+   .. tab-item:: Image IO
+
+      .. code-block:: yaml
+          python:
+              packages:
+              - "bentoml[io-image]"
+
+   .. tab-item:: Pandas IO
+
+      .. code-block:: yaml
+          python:
+              packages:
+              - "bentoml[io-pandas]"
+
+   .. tab-item:: Jaeger
+
+      .. code-block:: yaml
+          python:
+              packages:
+              - "bentoml[tracing-jaeger]"
+
+   .. tab-item:: Zipkin
+
+      .. code-block:: yaml
+          python:
+          packages:
+          - "bentoml[tracing-zipkin]"
+
+   .. tab-item:: OpenTelemetry Protocol
+
+      .. code-block:: yaml
+          python:
+              packages:
+              - "bentoml[tracing-otlp]"
+
 If you already have a
 `requirements.txt <https://pip.pypa.io/en/stable/reference/requirements-file-format/>`_
 file that defines python packages for your project, you may also supply a path to the

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -1,17 +1,14 @@
 from datetime import datetime
 
-try:
-    from importlib.metadata import version as _get_version
-except ImportError:
-    from importlib_metadata import version as _get_version
+from bentoml import __version__
 
 # -- Project information -----------------------------------------------------
 
 project = "BentoML"
 copyright = f"2022-{datetime.now().year}, bentoml.com"
 author = "bentoml.com"
 
-version = _get_version("bentoml")
+version = __version__
 
 # -- General configuration ---------------------------------------------------
 
@@ -69,7 +66,7 @@
 myst_enable_extensions = ["colon_fence"]
 
 # Remove the prompt when copying examples
-copybutton_prompt_text = r">>> |\.\.\.|» |\% |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
+copybutton_prompt_text = r">>> |\.\.\.|> |» |\% |\$ "
 copybutton_prompt_is_regexp = True
 copybutton_line_continuation_character = "\\"
 copybutton_here_doc_delimiter = "EOT"

diff --git a/docs/source/guides/tracing.rst b/docs/source/guides/tracing.rst
@@ -4,6 +4,31 @@ Tracing
 
 BentoML API server supports tracing with `Zipkin <https://zipkin.io/>`_,
 `Jaeger <https://www.jaegertracing.io/>`_ and `OTLP <https://opentelemetry.io/>`_.
+
+:bdg-info:`Requirements:` bentoml must be installed with the extras dependencies for
+tracing exporters. The following command will install BentoML with its coresponding
+tracing exporter:
+
+.. tab-set::
+
+   .. tab-item:: Jaeger
+
+       .. code-block:: bash
+
+          pip install "bentoml[tracing-jaeger]"
+
+   .. tab-item:: Zipkin
+
+      .. code-block:: bash
+
+         pip install "bentoml[tracing-zipkin]"
+
+   .. tab-item:: OpenTelemetry Protocol
+
+      .. code-block:: bash
+
+         pip install "bentoml[tracing-otlp]"
+
 To config tracing server, user can provide a config YAML file specifying the tracer type and tracing server information:
 
 .. code-block:: yaml
@@ -20,12 +45,6 @@ To config tracing server, user can provide a config YAML file specifying the tra
         protocol: grpc
         url: http://localhost:4317
 
-First, bentoml must be installed with the extras "tracing".
-
-.. code-block:: bash
-
-    pip install bentoml[tracing]
-
 By default, no traces will be collected. Set sample_rate to your desired fraction in order to start collecting them.
 Here is an example config for tracing with a Zipkin server:
 

diff --git a/docs/source/installation.rst b/docs/source/installation.rst
@@ -2,26 +2,97 @@
 Installation
 ============
 
-BentoML is distributed as a Python package available `on PyPI <https://pypi.org/project/bentoml/>`_.
+🍱 BentoML is distributed as a Python Package available `on PyPI <https://pypi.org/project/bentoml/>`_.
+Install BentoML alongside with whichever deep learning library you are working with, and you are ready to go!
 
 * BentoML supports Linux/UNIX, Windows, and MacOS.
 * BentoML requires Python 3.7 or above.
 
+.. code-block::
+
+   pip install bentoml
+
+To install all additional features in BentoML, such as gRPC, S3 support, and more, use the ``all`` variant. Features can also be installed separate later.
+
+.. code-block:: bash
+
+    pip install "bentoml[all]"
+
+Install from Source
+-------------------
+
+If you want to install BentoML from source, run the following command:
+
 .. code-block:: bash
 
-    pip install bentoml
+    pip install git+https://github.com/bentoml/bentoml
+
+This will install the bleeding edge ``main`` version of BentoML. The ``main`` version is
+useful for stay-up-to-date with the latest features and bug fixes. However, this means
+that ``main`` version is not always stable. If you run into any issues, please either
+create `an issue <https://github.com/bentoml/BentoML/issues/new/choose>`_ or join our
+`community Slack <https://l.linklyhq.com/l/ktOX>`_ to get help.
 
-You may need to install additional libraries to use certain BentoML modules or features.
-For example, the :code:`bentoml.tensorflow` module requires TensorFlow to be installed;
-The :code:`bentoml.io.Image` class requires :code:`Pillow` to be installed; and to
-export saved models to s3, the :code:`fs-s3fs` package is required.
+Editable Install
+----------------
 
+You may want an editable install if:
+
+* You want to stay-up-to-date with the latest features and bug fixes
+* You want to contribute to 🍱 BentoML and test code changes
 
 .. note::
 
-    Historical releases can be found on the `BentoML Releases page <https://github.com/bentoml/BentoML/releases>`_.
+   Make sure that you have the following requirements:
+    - `Git <https://git-scm.com/>`_
+    - `pip <https://pip.pypa.io/en/stable/installation/>`_
+    - `Python3.7+ <https://www.python.org/downloads/>`_
 
 .. seealso::
 
-    For the 0.13-LTS releases, see the `0.13-LTS documentation <https://docs.bentoml.org/en/v0.13.1/>`_.
+   You're always welcome to make contributions to the project and its documentation. Check out the
+    `BentoML development guide <https://github.com/bentoml/BentoML/blob/main/DEVELOPMENT.md>`_
+    and `documentation guide <https://github.com/bentoml/BentoML/blob/main/docs/README.md>`_
+    to get started.
+
+Clone the repository to your local folder and install 🍱 BentoML with the following command:
+
+.. code-block:: bash
+
+    git clone https://github.com/bentoml/bentoml.git
+    cd bentoml
+    pip install -e .
+
+This command will install 🍱 BentoML in `editable mode
+<https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs>`_,
+which allows you to install the project without copying any files. Python will link this
+folder and add it to Python library paths. This means that any changes you make to the
+folder will and can be tested immediately.
+
+.. dropdown:: For user using ``setuptools>=64.0.0``
+   :icon: question
+
+   BentoML uses `setuptools <https://setuptools.pypa.io/en/latest/>`_ to build and
+   package the project. Since ``setuptools>=64.0.0``, setuptools implemented `PEP 660 <https://peps.python.org/pep-0660/>`_, which changes the behavior of editable install in comparison with previous version of setuptools.
+
+   Currently, BentoML is not compatible with this new behavior. To install BentoML in editable mode, you have to pass ``--config-settings editable_mode=compat`` to ``pip``.
+
+   .. code-block:: bash
+
+      pip install -e ".[grpc]" --config-settings editable_mode=compat
+
+   See setuptools' `development mode guide <https://setuptools.pypa.io/en/latest/userguide/development_mode.html>`_ for more information.
+
+
+.. warning::
+
+   You must not remove ``bentoml`` folder after installing in editable mode to keep using
+   the library.
+
+After that you can easily update your clone with the latest changes on ``main`` branch
+with the following command:
+
+.. code-block:: bash
 
+    cd bentoml
+    git pull
diff --git a/docs/source/reference/api_io_descriptors.rst b/docs/source/reference/api_io_descriptors.rst
@@ -48,6 +48,12 @@ NumPy ``ndarray``
 Tabular Data with Pandas
 ------------------------
 
+To use the IO descriptor, install bentoml with extra ``io-pandas`` dependency:
+
+.. code-block:: bash
+
+    pip install "bentoml[io-pandas]"
+
 .. note::
 
    The :code:`pandas` package is required to use the :obj:`bentoml.io.PandasDataFrame`
@@ -135,6 +141,13 @@ Texts
 Images
 ------
 
+To use the IO descriptor, install bentoml with extra ``io-image`` dependency:
+
+
+.. code-block:: bash
+
+    pip install "bentoml[io-image]"
+
 .. note::
 
    The :code:`Pillow` package is required to use the :obj:`bentoml.io.Image`.