improve documentation

docs/gen_readme.py

@@ -11,9 +11,9 @@ def prune_rst_links_and_remove_args(obj) -> str:
     docstring = inspect.getdoc(obj)
     assert (docstring)
 
-    docstring = re.sub(r':func:`([^`]+)`', r'`\1`', docstring)
-    docstring = re.sub(r':class:`([^`]+)`', r'`\1`', docstring)
-    docstring = re.sub(r':type:`([^`]+)`', r'`\1`', docstring)
+    docstring = re.sub(r':func:`([^`]+)`', r'*\1*', docstring)
+    docstring = re.sub(r':class:`([^`]+)`', r'*\1*', docstring)
+    docstring = re.sub(r':type:`([^`]+)`', r'*\1*', docstring)
     docstring = textwrap.dedent(docstring).strip()
 
     paragraphs = docstring.split('\n\n')

src/ai3/__init__.py

@@ -2,10 +2,9 @@
 
 """Provides the easy-to-use fine-grain algorithmic control over an existing *DNN*
 
-The framework currently features two methods for algorithmic swapping. :func:`convert`
-which swaps every module type of a *DNN* returning an object completely managed
-by |name| and :func:`swap_operation` which swaps specific operations out of the
-existing *DNN*.
+The framework currently features two methods for algorithmic swapping.
+:func:`convert` which converts the entire *DNN* and :func:`swap_operation`
+which swaps specific operations out of the existing *DNN*.
 """
 
 from typing import Mapping, Optional, Sequence, Type, Union
@@ -156,13 +155,12 @@ def swap_operation(
 
 
 def convert(module,
-                 algos: Optional[Mapping[str, AlgorithmicSelector]] = None,
-                 sample_input_shape: Optional[Sequence[int]] = None, *,
-                 dtype=None) -> Model:
+            algos: Optional[Mapping[str, AlgorithmicSelector]] = None,
+            sample_input_shape: Optional[Sequence[int]] = None, *,
+            dtype=None) -> Model:
     """
-    Swaps every module in an exsiting *DNN* for an implementation
-    of the user specified algorithm returning
-    a :class:`Model` completly managed by the framework.
+    Converts every operation in a *DNN* to an implementation of the user
+    specified algorithm returning a :class:`Model` completly managed by |name|.
 
     Algorithmic selection is performed by passing a mapping from strings
     containing names of the operations to swap to a :type:`AlgorithmicSelector`.

src/ai3/swap_torch.py

@@ -274,8 +274,8 @@ def trace_module(module: nn.Module,
 
 
 def convert_layers(complete_module: nn.Module, dtype,
-                        algos: Mapping[str, utils.AlgorithmicSelector],
-                        sample_input_shape: Optional[Sequence[int]] = None) -> List[layers.Layer]:
+                   algos: Mapping[str, utils.AlgorithmicSelector],
+                   sample_input_shape: Optional[Sequence[int]] = None) -> List[layers.Layer]:
     graph, with_shapes = trace_module(
         complete_module, sample_input_shape)