fix(docs): Add Python documentation for algorithm methods (#278)

* fix(docs): Add documentation for algorithm methods

* fix(docs): black

* fix: silence warnings related to typechecking

* fix: correct types and listen to mypy

* fix: correct corresponding type annotation

rustfst-python/mkdocs.yml

@@ -83,7 +83,7 @@ plugins:
  show_signature_annotations: true
  show_submodules: true
  watch:
- - rustfst-python/rustfst
+ - rustfst
  - docs
 repo_name: rustfst
 repo_url: https://github.com/garvys-org/rustfst

rustfst-python/rustfst/algorithms/compose.py

@@ -64,6 +64,17 @@ class ComposeFilter(Enum):
 
 
 class ComposeConfig:
+ """
+ Configuration for compose operation.
+
+ Args:
+ compose_filter: Filter which determines allowable matches during
+ composition operation.
+ connect: Connect the resulting FST after composition.
+ matcher1_config: Matcher configuration for left-hand FST.
+ matcher2_config: Matcher configuration for right-hand FST.
+ """
+
  def __init__(
  self,
  compose_filter: ComposeFilter = ComposeFilter.AUTOFILTER,

rustfst-python/rustfst/algorithms/connect.py

@@ -9,7 +9,8 @@
 
 def connect(fst: VectorFst) -> VectorFst:
  """
- This operation trims an Fst, removing states and trs that are not on successful paths.
+ This operation trims an Fst in-place, removing states and trs that are not on
+ successful paths.
 
  Examples :
 
@@ -22,8 +23,7 @@ def connect(fst: VectorFst) -> VectorFst:
  ![connect_out](https://raw.githubusercontent.com/Garvys/rustfst-images-doc/master/images/connect_out.svg?sanitize=true)
 
  Returns :
- self
-
+ fst
  """
 
  ret_code = lib.fst_connect(fst.ptr)

rustfst-python/rustfst/algorithms/minimize.py

@@ -11,6 +11,10 @@
 
 
 class MinimizeConfig:
+ """
+ Configuration for the minimization operation.
+ """
+
  def __init__(self, delta=None, allow_nondet=False):
  if delta is None:
  delta = KSHORTESTDELTA
@@ -27,10 +31,11 @@ def __init__(self, delta=None, allow_nondet=False):
 
 def minimize(fst: VectorFst) -> VectorFst:
  """
- minimize(fst)
- Minimize a FST in place
- :param fst: Fst
- :return: Fst
+ Minimize an FST in-place
+ Params:
+ fst: Fst
+ Returns:
+ fst
  """
  ret_code = lib.fst_minimize(fst.ptr)
  err_msg = "Error while minimizing FST"
@@ -41,11 +46,12 @@ def minimize(fst: VectorFst) -> VectorFst:
 
 def minimize_with_config(fst: VectorFst, config: MinimizeConfig) -> VectorFst:
  """
- minimize(fst, config)
- Minimize a FST in place
- :param fst: Fst
- :param config: MinimizeConfig
- :return: Fst
+ Minimize an FST in-place
+ Params:
+ fst: Fst
+ config: Configuration
+ Returns:
+ fst
  """
  ret_code = lib.fst_minimize_with_config(fst.ptr, config.ptr)
  err_msg = "Error while minimizing FST"

rustfst-python/rustfst/algorithms/optimize.py

@@ -12,7 +12,7 @@
 
 def optimize(fst: VectorFst):
  """
- Optimize an fst.
+ Optimize an fst in-place
  Args:
  fst: Fst to optimize.
  """
@@ -23,7 +23,7 @@ def optimize(fst: VectorFst):
 
 def optimize_in_log(fst: VectorFst):
  """
- Optimize an fst in the log semiring.
+ Optimize an fst in-place in the log semiring.
  Args:
  fst: Fst to optimize.
  """

rustfst-python/rustfst/algorithms/replace.py

@@ -1,5 +1,5 @@
 from __future__ import annotations
-from typing import List
+from typing import List, Tuple
 import ctypes
 from rustfst.ffi_utils import (
  lib,
@@ -17,7 +17,7 @@ class LabelFstPair(ctypes.Structure):
 
 
 def replace(
- root_idx: int, fst_list: List[(int, VectorFst)], epsilon_on_replace: bool
+ root_idx: int, fst_list: List[Tuple[int, VectorFst]], epsilon_on_replace: bool
 ) -> VectorFst:
  """
  Recursively replaces trs in the root FSTs with other FSTs.

rustfst-python/rustfst/algorithms/reverse.py

@@ -8,12 +8,17 @@
 from rustfst.fst.vector_fst import VectorFst
 
 
-def reverse(fst: VectorFst):
+def reverse(fst: VectorFst) -> VectorFst:
  """
- reverse(fst)
- reverse an fst
- :param fst: Fst
- :return: Fst
+ Reverse an Fst, returning a new Fst which accepts
+ the same language in reverse order.
+
+ Not to be confused with `inverse`, which does something
+ totally different!
+ Args:
+ fst: Fst to reverse
+ Returns:
+ Newly created, reversed Fst.
  """
 
  reversed_fst = ctypes.c_void_p()

rustfst-python/rustfst/algorithms/rm_epsilon.py

@@ -8,12 +8,13 @@
 from rustfst.fst.vector_fst import VectorFst
 
 
-def rm_epsilon(fst: VectorFst):
+def rm_epsilon(fst: VectorFst) -> VectorFst:
  """
- rm_epsilon(fst)
- rm_epsilon an fst
- :param fst: Fst
- :return: Fst
+ Return an equivalent FST with epsilon transitions removed.
+ Args:
+ fst: Fst
+ Returns:
+ Newly created FST with epsilon transitions removed.
  """
 
  rm_epsilon_fst = ctypes.c_void_p()

rustfst-python/rustfst/algorithms/shortest_path.py

@@ -1,4 +1,5 @@
 from __future__ import annotations
+from typing import Union
 import ctypes
 from rustfst.ffi_utils import (
  lib,
@@ -11,7 +12,18 @@
 
 
 class ShortestPathConfig:
- def __init__(self, nshortest: int = 1, unique: bool = False, delta=None):
+ """
+ Configuration for shortest-path operation.
+
+ Args:
+ nshortest: Number of shortest paths to return
+ unique: Return only unique label sequences
+ delta: Difference in weights considered significant
+ """
+
+ def __init__(
+ self, nshortest: int = 1, unique: bool = False, delta: Union[float, None] = None
+ ):
  if delta is None:
  delta = KSHORTESTDELTA
  config = ctypes.pointer(ctypes.c_void_p())
@@ -28,10 +40,11 @@ def __init__(self, nshortest: int = 1, unique: bool = False, delta=None):
 
 def shortestpath(fst: VectorFst) -> VectorFst:
  """
- shortestpath(fst)
- construct a FST containing the shortest path of the input FST
- :param fst: Fst
- :return: Fst
+ Construct a FST containing the shortest path of the input FST
+ Args:
+ fst: Fst
+ Returns:
+ Newly-created FST containing only the shortest path of the input FST.
  """
 
  shortest_path = ctypes.c_void_p()
@@ -44,11 +57,12 @@ def shortestpath(fst: VectorFst) -> VectorFst:
 
 def shortestpath_with_config(fst: VectorFst, config: ShortestPathConfig) -> VectorFst:
  """
- shortestpath(fst,config)
- construct a FST containing the n-shortest path(s) in the input FST
- :param fst: Fst
- :param config: ShortestPathConfig
- :return: Fst
+ Construct a FST containing the shortest path of the input FST
+ Args:
+ fst: Fst
+ config: Configuration for shortest-path operation.
+ Returns:
+ Newly-created FST containing only the shortest path of the input FST.
  """
 
  shortest_path = ctypes.c_void_p()