README.md

BentoML Documentation

This directory contains the sphinx source text for BentoML docs, visit http://docs.bentoml.org/ to read the full documentation.

---

NOTE: All of the below make commands should be used under bentoml root directory. Only MacOS and Linux (UNIX-based system only) are supported at the moment for live reloading of the documentation

To generate the documentation, make sure to install all dependencies (mainly sphinx and its extension):

» make install-docs-deps

Once you have sphinx installed, you can build the documentation and enable watch on changes:

» make watch-docs

For Apple Silicon (M1), follow the latest suggested installation method for PyEnchant As of this writing there is no compatible arm64 version of pyenchant and the best way to install is the following commands:

» arch -x86_64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
» arch -x86_64 /usr/local/bin/brew install enchant

Make sure that PYENCHANT_LIBRARY_PATH is set to the location of libenchant. For MacOS make sure it has the dylib extension, otherwise the .so for Linux based systems.

Documentation specification

bentoml/BentoML follows Google's docstring style, mostly written in ReStructuredText

Writing source documentation

Value should either put around ``double backticks``, or put into a :code:`codeblock` or using the object syntax :obj:`class`. When mentioning a class it is recommended to use the :class:`syntax` as mentioned class will be linked by Sphinx:

:class:`~bentoml.BentoService`

When mentioning a function, it is recommended to use the :func:`syntax` as mentioned function will be linked by Sphinx:

:func:`~bentoml.yatai.client.func`

When mentioning a method, it is recommended to use the :meth:`syntax` as mentioned method will be linked by Sphinx:

:meth:`~bentoml.BentoService.method`

Define arguments in a method

Arguments should be defined with Args: prefix, followed by a line with indentation. Each argument should be followed by its type, a new indentation for description of given field. Each argument should follow the below definition:

    Args:
        bento_name (:code:`str`):
            :class:`~bentoml.BentoService` identifier with name format :obj:`NAME:VERSION`.
            ``NAME`` can be accessed via :meth:`~bentoml.BentoService.name` and ``VERSION`` can
            be accessed via :meth:`~bentoml.BentoService.version`

For optional arguments, follow the following syntax. For example a function func() with following signature:

def func(x: str=None, a: Optional[bool]=None):
    ...

then documentation should look like:

    Args:
        x (:code:`str`, `optional`):
            Description of x ...
        a (`bool`, `optional`):
            Description of a ...

Define a multiline code block in a method

Make sure to define something like:

Example::

    # example code here
    # ...

The Example can be replaced with any word of choice as long as there are two semicolons following. Read more about doctest

Define a return block in a method

If a function returns value, returns should be defined with Returns:, followed by a line with indentation. The first line should be the type of the return, followed by a line return. An example for a return statement:

    Returns:
        :obj:`Dict[str,str]` with keys are :class:`~bentoml.BentoService` nametag following with saved bundle path.

Model docstring specification

When adding a new integration with a deep learning framework, make sure to document the Model class correctly following the below template:

    from bentoml._internal.models import Model


class FooBarArtifact(Model):
    """
    Model class for saving/loading :obj:`mlflow` models

    Args:
        model (:code:`mlflow.models.Model`):
            All mlflow models are of type :obj:`mlflow.models.Model`
        metadata (:code:`Dict[str, Any]`, or :obj:`~bentoml._internal.types.MetadataType`, `optional`, default to :code:`None`):
            Class metadata
        ... # Custom parameters

    Raises:
        MissingDependencyException:
            :obj:`mlflow` is required by MLflowModel
        ArtifactLoadingException:
            given `loader_module` is not supported by :obj:`mlflow`

    Example usage under :code:`train.py`::

        TODO:

    One then can define :code:`service.py`::

        TODO:

    Containerize a bento with :code:`bento_packer.py`::

        TODO:
    """  # noqa: E501

Tips and Tricks

Header level hierarchy in rst:

1 -
2 ~
3 ^
4 =
5 "