Add contributing file and Sphynx documentation (nebuly-ai#57)

* add Contributing file

* Update contributed file

* add sphinx documentation (nebuly-ai#36)

* add sphinx config files

* update imports and docstring inline

* add readme

Co-authored-by: Diego Fiori <[email protected]>

* solve code-style inconsistencies

* change documentation style to furo

* Edit conf.py to customize documentation

* clear notebook output

* replace relative imports with full imports

Co-authored-by: morgoth95 <[email protected]>
Co-authored-by: Nebuly <[email protected]>
Co-authored-by: czab092 <[email protected]>

.gitignore

@@ -128,6 +128,3 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
-
-# Pre-commit config file
-.pre-commit-config.yaml

.pre-commit-config.yaml

@@ -0,0 +1,11 @@
+repos:
+  - repo: https://github.com/ambv/black
+    rev: 22.3.0
+    hooks:
+      - id: black
+        args: [--line-length=79]
+
+  - repo: https://gitlab.com/pycqa/flake8
+    rev: 3.9.2
+    hooks:
+      - id: flake8

CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Guidelines for Contributing to Nebullvm.
+
+Hello coder 👋
+
+We are very happy that you have decided to contribute to the library and we thank you for your efforts. Below we briefly lay out the main guidelines for conforming your code to the coding style we have adopted for `nebullvm`.
+
+We hope to come across your pull request soon!
+
+Happy coding 💫 The nebullvm Team
+
+
+## How to submit an issue
+Did you spot a bug? Did you come up with a cool idea that you think should be implemented in nebullvm? Well, GitHub issues are the best way to let us know!
+
+We don't have a strict policy on issue generation: just use a meaningful title and specify the problem or your proposal in the first problem comment. Then, you can use GitHub labels to let us know what kind of proposal you are making, for example `bug` if you are reporting a new bug or `enhancement` if you are proposing a library improvement. 
+
+## How to contribute to solve an issue
+We are always delighted to welcome other people to the contributor section of `nebullvm`! We are looking forward to welcoming you to the community, but before you rush off and write 1000 lines of code, please take a few minutes to read our tips for contributing to the library.
+* Please fork the library instead of pulling it and creating a new branch.
+* Work on your fork and, when you think the problem has been solved, open a pull request.
+* In the pull request specify which problems the it is solving/closing. For instance, if the pull request solves problem #1, the comment should be `Closes #1`.
+* The title of the pull request must be meaningful and self-explanatory.
+
+
+## Coding style
+Before you git commit and push your code, please use `black` to format your code. We strongly recommend that you install `pre-commit` to reformat your code when you commit your changes.
+
+To use the formatting style defined for nebullvm, run the following commands:
+```bash
+pip install pre-commit black autoflake
+pre-commit install
+# the following command is optional, but needed if you have already committed some files to your forked repo.
+pre-commit run --all-files
+```
+Then add and commit all changes!
+
+As for the naming convention, we follow [PEP 8](https://peps.python.org/pep-0008/) for code and a slight variation of [Google convention](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) for docstrings. For docstrings we redundantly express the input type in both the function definition and the function docstring.
+
+---
+
+See you soon in the list of nebullvm contributors ✨

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/README.md

@@ -0,0 +1,11 @@
+# Documentation
+Nebullvm documentation is built using Sphynx and furo! You can follow the guide below for
+## Build the docs:
+
+1. Install nebullvm according to [README.md](../README.md#step-1-installation-of-nebullvm-library).
+2. Install additional libraries required to build docs:
+```
+pip install -r requirements-docs.txt
+```
+3. Run `make html` from this directory.
+

docs/conf.py

@@ -0,0 +1,108 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# 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.
+#
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../"))
+
+# import sphinx_rtd_theme
+
+# -- Project information -----------------------------------------------------
+
+project = "nebullvm"
+copyright = "2022, nebuly"
+author = "nebuly"
+
+# The full version, including alpha/beta/rc tags
+#release = "0.3.0"
+
+
+# -- General configuration ---------------------------------------------------
+
+# 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.napoleon",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx.ext.coverage",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.githubpages",
+]
+
+# -- Configurations for plugins ------------
+napoleon_google_docstring = True
+napoleon_include_init_with_doc = True
+napoleon_include_special_with_doc = True
+napoleon_numpy_docstring = False
+napoleon_use_rtype = False
+autodoc_inherit_docstrings = False
+autodoc_member_order = "bysource"
+
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- 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 = "sphinx_rtd_theme"
+html_theme = "furo"
+
+html_theme_options = {
+    "light_css_variables": {
+        "color-brand-primary": "#dark",
+        "color-brand-content": "#dark",
+        "color-admonition-background": "#dark",
+        "font-stack": "Montserrat, sans-serif",
+        "font-stack--monospace": "Courier, monospace",
+    },
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/nebuly-ai/nebullvm",
+            "html": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+                    <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
+                </svg>
+            """,
+            "class": "",
+        },
+    ],
+    "light_logo": "Logo_azure.svg",
+    "dark_logo":  "Logo_azure.svg",
+}
+
+
+html_static_path = ["_static"]
+html_title = ""
+
+
+#html_theme_options = {
+#    "announcement": "<em>Important</em> announcement!",
+#}
+
+# 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']

docs/index.rst

@@ -0,0 +1,8 @@
+Welcome to nebullvm's documentation!
+======================================
+
+.. toctree::
+   :maxdepth: 2
+
+   modules/index
+

docs/modules/api.rst

@@ -0,0 +1,9 @@
+nebullvm.api
+=============
+
+.. automodule:: nebullvm
+    :members:
+
+.. automodule:: nebullvm.api.frontend.huggingface
+    :members:
+

docs/modules/converters.rst

@@ -0,0 +1,5 @@
+nebullvm.converters
+===================
+
+.. automodule:: nebullvm.converters
+    :members:

docs/modules/index.rst

@@ -0,0 +1,10 @@
+API Documentation
+==================
+
+.. toctree::
+
+    api
+    converters
+    inference_learners
+    installers
+    optimizers

docs/modules/inference_learners.rst

@@ -0,0 +1,5 @@
+nebullvm.inference_learners
+===========================
+
+.. automodule:: nebullvm.inference_learners
+    :members:

docs/modules/installers.rst

@@ -0,0 +1,5 @@
+nebullvm.installers
+===================
+
+.. automodule:: nebullvm.installers
+    :members:

docs/modules/optimizers.rst

@@ -0,0 +1,5 @@
+nebullvm.optimizers
+===================
+
+.. automodule:: nebullvm.optimizers
+    :members:

docs/requirements-docs.txt

@@ -0,0 +1,4 @@
+Sphinx==4.5.0
+coloredlogs
+sympy
+furo

nebullvm/__init__.py

@@ -1,3 +1,5 @@
 from nebullvm.api.frontend.torch import optimize_torch_model  # noqa F401
 from nebullvm.api.frontend.tf import optimize_tf_model  # noqa F401
 from nebullvm.api.frontend.onnx import optimize_onnx_model  # noqa F401
+
+__all__ = [k for k in globals().keys() if not k.startswith("_")]

nebullvm/api/frontend/tf.py

@@ -163,7 +163,7 @@ def optimize_tf_model(
     Returns:
         BaseInferenceLearner: Optimized model usable with the classical
             tensorflow interface. Note that as a torch model it takes as input
-            and it gives as output `tf.Tensor`s.
+            and it gives as output `tf.Tensor` s.
     """
     if dataset is not None:
         (

nebullvm/api/frontend/torch.py

@@ -185,7 +185,7 @@ def optimize_torch_model(
     Returns:
         PytorchBaseInferenceLearner: Optimized model usable with the classical
             Pytorch interface. Note that as a torch model it takes as input
-            and it gives as output `torch.Tensor`s.
+            and it gives as output `torch.Tensor` s.
     """
     check_inputs(
         input_data=dataloader, batch_size=batch_size, input_sizes=input_sizes

nebullvm/converters/__init__.py

@@ -1 +1,10 @@
-from .converters import ONNXConverter  # noqa F401
+# flake8: noqa
+
+from nebullvm.converters.converters import BaseConverter, ONNXConverter
+from nebullvm.converters.tensorflow_converters import (
+    convert_tf_to_onnx,
+    convert_keras_to_onnx,
+)
+from nebullvm.converters.torch_converters import convert_torch_to_onnx
+
+__all__ = [k for k in globals().keys() if not k.startswith("_")]

nebullvm/inference_learners/__init__.py

@@ -0,0 +1,31 @@
+# flake8: noqa
+
+from nebullvm.inference_learners.base import (
+    BaseInferenceLearner,
+    LearnerMetadata,
+    PytorchBaseInferenceLearner,
+    TensorflowBaseInferenceLearner,
+    InferenceLearnerWrapper,
+)
+from nebullvm.inference_learners.onnx import (
+    ONNXInferenceLearner,
+    PytorchONNXInferenceLearner,
+    TensorflowONNXInferenceLearner,
+)
+from nebullvm.inference_learners.openvino import (
+    OpenVinoInferenceLearner,
+    PytorchOpenVinoInferenceLearner,
+    TensorflowOpenVinoInferenceLearner,
+)
+from nebullvm.inference_learners.tensor_rt import (
+    NvidiaInferenceLearner,
+    PytorchNvidiaInferenceLearner,
+    TensorflowNvidiaInferenceLearner,
+)
+from nebullvm.inference_learners.tvm import (
+    ApacheTVMInferenceLearner,
+    PytorchApacheTVMInferenceLearner,
+    TensorflowApacheTVMInferenceLearner,
+)
+
+__all__ = [k for k in globals().keys() if not k.startswith("_")]

nebullvm/inference_learners/openvino.py

@@ -148,7 +148,8 @@ def from_model_name(
     def _rebuild_network(self, input_shapes: Dict):
         network = self.exec_network.get_exec_graph_info()
         if all(
-            input_shape == tuple(network.input_info[input_name].input_data.shape)
+            input_shape
+            == tuple(network.input_info[input_name].input_data.shape)
             for input_name, input_shape in input_shapes.items()
         ):
             # If the new input shapes is equal to the previous one do nothing.

nebullvm/installers/__init__.py

@@ -0,0 +1,10 @@
+# flake8: noqa
+
+from nebullvm.installers.installers import (
+    install_tvm,
+    install_tensor_rt,
+    install_openvino,
+    install_onnxruntime,
+)
+
+__all__ = [k for k in globals().keys() if not k.startswith("_")]

nebullvm/optimizers/__init__.py

@@ -3,3 +3,5 @@
 from nebullvm.optimizers.openvino import OpenVinoOptimizer  # noqa F401
 from nebullvm.optimizers.tensor_rt import TensorRTOptimizer  # noqa F401
 from nebullvm.optimizers.tvm import ApacheTVMOptimizer  # noqa F401
+
+__all__ = [k for k in globals().keys() if not k.startswith("_")]