Updating documentation

.gitignore

@@ -1,5 +1,6 @@
 */*.pyc
 */__pycache__
+html
 .idea
 .coverage
 .pytest_cache

README.md

@@ -1,3 +1,29 @@
 # pybergamot
 
 (Somewhat) stable interface for the **Bergamot Translation Engine Python Bindings**.
+
+## Generate documentation
+
+Documentation for `pybergamot` can be generated using [pdoc](https://pdoc.dev).
+
+Use the script `build-doc.sh` to generate the documentation directly.
+
+## Legal
+
+        pybergamot - (Somewhat) stable interface for the **Bergamot Translation Engine Python Bindings**.
+        Copyright (C) 2023 Ad5001 <mail@ad5001.eu>
+
+        This program is free software: you can redistribute it and/or modify
+        it under the terms of the GNU General Public License as published by
+        the Free Software Foundation, either version 3 of the License, or
+        (at your option) any later version.
+
+        This program is distributed in the hope that it will be useful,
+        but WITHOUT ANY WARRANTY; without even the implied warranty of
+        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+        GNU General Public License for more details.
+
+        You should have received a copy of the GNU General Public License
+        along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+This project is not affiliated to the Bergamot Project or Mozilla.

build-doc.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+python3 -m pdoc --force --html pybergamot
+
+cd html/pybergamot || exit
+
+python3 -m http.server 8080

pybergamot/__init__.py

@@ -1 +1,6 @@
+"""
+Welcome to pybergamot!
+
+
+"""
 from .translator import Translator

pybergamot/engine.py

@@ -46,18 +46,27 @@ class Engine(ABC):
     def translate(self, text: str, html: bool = False, alignment: bool = False, quality_scores: bool = False) -> str:
         """
         Translates the text from the engine's source lang its target.
-        :param text: Text to translate.
+
-        :param html: Set to True if the text contains an HTML structure which needs to
+        ## Parameters
+        ---
+        - **text**: Text to translate.    
+        - **html**: Set to True if the text contains an HTML structure which needs to
                      be preserved while translated.    
-        :param alignment: Toggle for alignment.
+        - **alignment**: Toggle for alignment.    
-        :param quality_scores: Toggle for whether to include the translation's quality scores
+        - **quality_scores**: Toggle for whether to include the translation's quality scores
                                for each word in HTML format.    
-        :return: The translated text.
+
+        ## Returns
+        ---
+        The translated text.
         """
         pass
 
 
 class DirectBergamotModelEngine(Engine):
+    """
+    Internal module. Engine using a single bergamot model to translate.
+    """
     def __init__(self, source_lang: str, target_lang: str, model: TranslationModel,
                  service: Service):
         self._source_lang = source_lang
@@ -82,6 +91,9 @@ class DirectBergamotModelEngine(Engine):
 
 
 class ChainBergamotModelsEngine(Engine):
+    """
+    Internal module. Engine chaining two bergamot model to translate.
+    """
     def __init__(self, source_lang: str, target_lang: str, model1: TranslationModel,
                  model2: TranslationModel, service: Service):
         self._source_lang = source_lang

pybergamot/models.py

@@ -64,10 +64,19 @@ class Models:
     def get_model_languages(model_name: str) -> tuple:
         """
         Returns a tuple of two two-char ISO language name which the model translates from and to.
-        :param model_name: Name of the model
+
-        :raises:
+        ## Parameters
-            ValueError: When the model_name doesn't exist.
+        ---
-        :return: (from language, to language)
+        - **model_name**: Name of the model    
+
+        ## Exceptions
+        ---
+        - `ValueError`: When the model_name doesn't exist.
+
+        ## Returns
+        ---
+        (from language, to language)
+
         """
         if model_name not in Models.AVAILABLE:
             raise ValueError(f"Model {model_name} does not exist. Did you update the repository cache?")
@@ -83,9 +92,16 @@ class Models:
     def get_model_name_for_languages(source_lang: str, target_lang: str) -> str | None:
         """
         Finds a model which translates source_lang into target_lang.
-        :param source_lang: Language to translate from.
+
-        :param target_lang: Language to translate to.
+        ## Parameters
-        :return: None if no model was found, name of the model otherwise.
+        ---
+        - **source_lang**: Language to translate from.    
+        - **target_lang**: Language to translate to.    
+
+        ## Returns
+        ---
+        None if no model was found, name of the model otherwise.
+
         """
         lang_tuple = (source_lang, target_lang)
         names = list(filter(lambda name: lang_tuple == Models.get_model_languages(name), Models.AVAILABLE))
@@ -99,9 +115,14 @@ class Models:
     def download(model_name: str) -> None:
         """
         Downloads or updates the given model.
-        :param model_name: Name of the model to download.
+
-        :raises:
+        ## Parameters
-            ValueError: When the model_name doesn't exist.
+        ---
+        - **model_name**: Name of the model to download.    
+
+        ## Exceptions
+        ---
+        - `ValueError`: When the model_name doesn't exist.
         """
         if model_name not in Models.AVAILABLE:
             raise ValueError(f"Model {model_name} does not exist. Did you update the repository cache?")

pybergamot/translator.py

@@ -27,17 +27,21 @@ class Translator:
     """
     Main exposed class to provide translation using Bergamot.
     Workflow goes as follows:
+
     1. Create instance
     2. Load languages
     3. Use translation between any of the loaded language.
 
     """
-    def __init__(self, workers_count = 1, cache_size = 0, log_level = 'off'):
+    def __init__(self, workers_count=1, cache_size=0, log_level='off'):
         """
         Creates a Translator instance.
-        :param workers_count: Number of workers which can be used at once.
+
-        :param cache_size: Size of the cache used in bergamot..
+        ## Parameters
-        :param log_level: Level of logs used in bergamot.
+        ---
+        - **workers_count**: Number of workers which can be used at once.
+        - **cache_size**: Size of the cache used in bergamot.
+        - **log_level**: Level of logs used in bergamot.
         """
         self.loaded_languages = []
         self._loaded_engines = {}
@@ -47,13 +51,21 @@ class Translator:
     def _load_model(self, model_name: str, download: bool = True) -> TranslationModel:
         """
         Loads a tiny model by its name, downloads it if it doesn't exist.
-        :param model_name: Name of the model to load.
+        
-        :param download: If a model does not exist locally, if True, download it,
+        ## Parameters
-                         otherwise emit an error.
+        ---
-        :raises:
+        - **model_name**: Name of the model to load.    
-            ValueError: If the provided model does not exist.
+        - **download**: If a model does not exist locally, if True, download it,
-            EnvironmentError: When a model is unavailable and download has been set to false.
+                        otherwise emit an error.
-        :return: Bergamot translation model instance.
+
+        ## Exceptions
+        ---
+        - `ValueError`: If the provided model does not exist.
+        - `EnvironmentError`: When a model is unavailable and download has been set to false.
+
+        ## Returns
+        ---
+         Bergamot translation model instance.
         """
         if model_name not in Models.AVAILABLE:
             raise ValueError(f"Model {model_name} not available.")
@@ -71,14 +83,22 @@ class Translator:
     def _create_engine(self, source_lang: str, target_lang: str, download: bool = True) -> Engine:
         """
         Creates an Engine to translate a source lang to a target lang.
-        :param source_lang: Language to translate from.
+
-        :param target_lang: Language to translate to.
+        ## Parameters
-        :param download: If a model does not exist locally, if True, download it,
+        ---
+        - **source_lang**: Language to translate from.    
+        - **target_lang**: Language to translate to.    
+        - **download**: If a model does not exist locally, if True, download it,
                          otherwise emit an error.    
-        :raises:
+
-            ValueError: If a model from a lang to english does not exist.
+        ## Exceptions
-            EnvironmentError: When a model is unavailable and download has been set to false.
+        ---
-        :return: Engine instance.
+        - `ValueError`: If a model from a lang to english does not exist.
+        - `EnvironmentError`: When a model is unavailable and download has been set to false.
+
+        ## Returns
+        ---
+         Engine instance.
         """
         direct_model_name = Models.get_model_name_for_languages(source_lang, target_lang)
         if direct_model_name is not None and (download or direct_model_name in Models.INSTALLED):
@@ -107,12 +127,16 @@ class Translator:
         Loads a language code and all the associated models (for already added languages)
         into the translator.
 
-        :param lang: Two-char ISO language name.
+        ## Parameters
-        :param download: If a model does not exist locally, if True, download it,
+        ---
+        - **lang**: Two-char ISO language name.    
+        - **download**: If a model does not exist locally, if True, download it,
                          otherwise emit an error.    
-        :raises:
+
-            ValueError: If a model from a lang to english does not exist.
+        ## Exceptions
-            EnvironmentError: When a model is unavailable and download has been set to false.
+        ---
+        - `ValueError`: If a model from a lang to english does not exist.
+        - `EnvironmentError`: When a model is unavailable and download has been set to false.
         """
         if lang not in Models.LANGS:
             raise ValueError(f"Language {lang} does not exist.")
@@ -136,17 +160,24 @@ class Translator:
         """
         Translates a text from a source lang to a target lang.
 
-        :param source_lang: Language to translate from.
+        ## Parameters
-        :param target_lang: Language to translate to.
+        ---
-        :param text: Text to translate.
+        - **source_lang**: Language to translate from.    
-        :param html: Set to True if the text contains an HTML structure which needs to
+        - **target_lang**: Language to translate to.    
+        - **text**: Text to translate.    
+        - **html**: Set to True if the text contains an HTML structure which needs to
                      be preserved while translated.    
-        :param alignment: Toggle for alignment.
+        - **alignment**: Toggle for alignment.    
-        :param quality_scores: Toggle for whether to include the translation's quality scores
+        - **quality_scores**: Toggle for whether to include the translation's quality scores
                                for each word in HTML format.
-        :raises:
+
-            ValueError: Either source_lang or target_lang haven't been loaded yet.
+        ## Exceptions
-        :return: The translated text.
+        ---
+        - `ValueError` Either source_lang or target_lang haven't been loaded yet.
+
+        ## Returns
+        ---
+         The translated text.
         """
         if source_lang not in self.loaded_languages:
             raise ValueError(f"Language {source_lang} is not loaded. Use the load() function first.")