gh-167: try minor docs gen fixes

SparseLinearAlgebra · Aug 29, 2023 · 2bc8204 · 2bc8204
1 parent 24f44dd
commit 2bc8204
Show file tree

Hide file tree

Showing 9 changed files with 36 additions and 65 deletions.
diff --git a/.github/workflows/docs-python.yml b/.github/workflows/docs-python.yml
@@ -24,10 +24,10 @@ jobs:
           python-version: ${{ matrix.python-version }}
 
       - name: Install packages
-        run: python -m pip install pdoc3
+        run: python -m pip install pdoc
 
       - name: Build docs
-        run: pdoc -o pydocs --html python/pyspla
+        run: pdoc -o pydocs python/pyspla
         env:
           SPLA_DOCS: true
 

diff --git a/README.md b/README.md
@@ -6,7 +6,7 @@
 [![Python Package](https://github.com/SparseLinearAlgebra/spla/actions/workflows/deploy.yml/badge.svg)](https://pypi.org/project/pyspla/)
 [![Python Package (Test)](https://github.com/SparseLinearAlgebra/spla/actions/workflows/deploy-test.yml/badge.svg)](https://test.pypi.org/project/pyspla/)
 [![Docs C/C++](https://github.com/SparseLinearAlgebra/spla/actions/workflows/docs-cpp.yml/badge.svg?branch=main)](https://SparseLinearAlgebra.github.io/spla/docs-cpp/)
-[![Docs Python](https://github.com/SparseLinearAlgebra/spla/actions/workflows/docs-python.yml/badge.svg?branch=main)](https://SparseLinearAlgebra.github.io/spla/docs-python/pyspla/)
+[![Docs Python](https://github.com/SparseLinearAlgebra/spla/actions/workflows/docs-python.yml/badge.svg?branch=main)](https://SparseLinearAlgebra.github.io/spla/docs-python/pyspla.html)
 [![Clang Format](https://github.com/SparseLinearAlgebra/spla/actions/workflows/clang-format.yml/badge.svg?branch=main)](https://github.com/SparseLinearAlgebra/spla/actions/workflows/clang-format.yml)
 [![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/SparseLinearAlgebra/spla/blob/master/LICENSE.md)
 
@@ -16,23 +16,23 @@ operations. It gives an ability to customize underlying values types treatment a
 or custom user-defined functions.
 
 - **Website**:
-  [https://SparseLinearAlgebra.github.io/pyspla/](https://SparseLinearAlgebra.github.io/spla/docs-python/pyspla/)
+  [SparseLinearAlgebra.github.io/pyspla](https://SparseLinearAlgebra.github.io/spla/docs-python/pyspla.html)
 - **Package page**:
-  [https://pypi.org/project/pyspla](https://pypi.org/project/pyspla/)
+  [pypi.org/project/pyspla](https://pypi.org/project/pyspla/)
 - **Package page (test)**:
-  [https://test.pypi.org/project/pyspla](https://test.pypi.org/project/pyspla/)
+  [test.pypi.org/project/pyspla](https://test.pypi.org/project/pyspla/)
 - **Source code**:
-  [https://github.com/SparseLinearAlgebra/spla](https://github.com/SparseLinearAlgebra/spla)
+  [github.com/SparseLinearAlgebra/spla](https://github.com/SparseLinearAlgebra/spla)
 - **Contributing**:
-  [https://github.com/SparseLinearAlgebra/spla/CONTRIBUTING.md](https://github.com/SparseLinearAlgebra/spla/blob/main/CONTRIBUTING.md)
+  [github.com/SparseLinearAlgebra/spla/CONTRIBUTING.md](https://github.com/SparseLinearAlgebra/spla/blob/main/CONTRIBUTING.md)
 - **Development**:
-  [https://github.com/SparseLinearAlgebra/spla/DEVELOPMENT.md](https://github.com/SparseLinearAlgebra/spla/blob/main/DEVELOPMENT.md)
+  [github.com/SparseLinearAlgebra/spla/DEVELOPMENT.md](https://github.com/SparseLinearAlgebra/spla/blob/main/DEVELOPMENT.md)
 - **Examples**:
-  [https://github.com/SparseLinearAlgebra/spla/EXAMPLES.md](https://github.com/SparseLinearAlgebra/spla/blob/main/EXAMPLES.md)
+  [github.com/SparseLinearAlgebra/spla/EXAMPLES.md](https://github.com/SparseLinearAlgebra/spla/blob/main/EXAMPLES.md)
 - **C/C++ API reference**:
-  [https://SparseLinearAlgebra.github.io/spla/docs-cpp](https://SparseLinearAlgebra.github.io/spla/docs-cpp/)
+  [SparseLinearAlgebra.github.io/spla/docs-cpp](https://SparseLinearAlgebra.github.io/spla/docs-cpp/)
 - **Bug report**:
-  [https://github.com/SparseLinearAlgebra/spla/issues](https://github.com/SparseLinearAlgebra/spla/issues)
+  [github.com/SparseLinearAlgebra/spla/issues](https://github.com/SparseLinearAlgebra/spla/issues)
 
 > Note: project under heavy development! Not ready for usage.
 

diff --git a/python/pyspla/__init__.py b/python/pyspla/__init__.py
@@ -118,9 +118,9 @@
 `ONE`    | binary(x,y) | r = 1
 `MIN`    | binary(x,y) | r = min(x, y)
 `MAX`    | binary(x,y) | r = max(x, y)
-`BOR`    | binary(x,y) | r = x | y, for integral only
-`BAND`   | binary(x,y) | r = x & y, for integral only
-`BXOR`   | binary(x,y) | r = x ^ y, for integral only
+`BOR`    | binary(x,y) | r = x or y
+`BAND`   | binary(x,y) | r = x & y
+`BXOR`   | binary(x,y) | r = x ^ y
 
 List of built-in select operations:
 

diff --git a/python/pyspla/array.py b/python/pyspla/array.py
@@ -39,13 +39,6 @@ class Array(Object):
     """
     Generalized statically-typed dense linear array primitive.
 
-    Attributes
-    ----------
-
-    - dtype  : `Type` type of stored array elements
-    - n_vals : `int` number of values in the array
-    - shape  : `2-tuple` shape of the array in form of two integers tuple (second dim is 1)
-
     Notes
     -----
 
@@ -82,16 +75,16 @@ def __init__(self, dtype=INT, shape=None, hnd=None, label=None):
         Parameters
         ----------
 
-        dtype: Type.
+        :param dtype: Type.
             Type parametrization of a storage.
 
-        shape: optional: int. default: None.
+        :param shape: optional: int. default: None.
             Size of the array.
 
-        hnd: optional: ctypes.c_void_p. default: None.
+        :param hnd: optional: ctypes.c_void_p. default: None.
             Optional native handle to retain.
 
-        label: optional: str. default: None.
+        :param label: optional: str. default: None.
             Optional label to assign.
         """
 
@@ -151,10 +144,10 @@ def set(self, index, value):
         Parameters
         ----------
 
-        index: int.
+        :param index: int.
             Index at which value to set.
 
-        value: any.
+        :param value: any.
             Value to set, must be convertible to destination type.
         """
 
@@ -167,7 +160,7 @@ def get(self, index):
         Parameters
         ----------
 
-        index: int.
+        :param index: int.
             Index at which to get value.
 
         Returns
@@ -187,7 +180,7 @@ def build(self, view: MemView):
         Parameters
         ----------
 
-        view: MemView.
+        :param view: MemView.
             View to a memory to build the array content from.
         """
 
@@ -214,7 +207,7 @@ def resize(self, shape=0):
         Parameters
         ----------
 
-        shape: optional: int. default: 0.
+        :param shape: optional: int. default: 0.
             New array capacity.
         """
 
@@ -251,10 +244,10 @@ def from_list(cls, values, dtype=INT):
         Parameters
         ----------
 
-        values: List.
+        :param values: List.
             List with values to fill array.
 
-        dtype: Type.
+        :param dtype: Type.
             Type of the array stored value.
 
         Returns
@@ -278,16 +271,16 @@ def generate(cls, dtype=INT, shape=0, seed=None, dist=(0, 1)):
         Parameters
         ----------
 
-        dtype: Type.
+        :param dtype: Type.
             Type of values array will have.
 
-        shape: optional: int. default: 0.
+        :param shape: optional: int. default: 0.
             Size of the array (number of values).
 
-        seed: optional: int. default: None.
+        :param seed: optional: int. default: None.
             Optional seed to randomize generator.
 
-        dist: optional: tuple. default: [0,1].
+        :param dist: optional: tuple. default: [0,1].
             Optional distribution for uniform generation of values.
 
         Returns

diff --git a/python/pyspla/memview.py b/python/pyspla/memview.py
@@ -36,13 +36,6 @@ class MemView(Object):
     """
     Wrapper for a memory view object from a library.
 
-    Attributes
-    ----------
-
-    - buffer : `ctypes.c_void_p` hnd to native raw memory buffer
-    - size : `int` size of the buffer in bytes
-    - is_mutable : `bool` whenever buffer content can be modified
-
     Details
     -------
 

diff --git a/python/pyspla/object.py b/python/pyspla/object.py
@@ -35,12 +35,6 @@ class Object:
     """
     Base class for any spla library object.
 
-    Attributes
-    ----------
-
-    - label : `str` user provided text label for object for debugging
-    - hnd : `ctypes.c_void_p` hnd to native object in spla C API
-
     Details
     -------
 

diff --git a/python/pyspla/scalar.py b/python/pyspla/scalar.py
@@ -37,12 +37,6 @@ class Scalar(Object):
     """
     Generalized statically-typed scalar primitive.
 
-    Attributes
-    ----------
-
-    - dtype : `type` type of stored matrix elements
-    - shape : `2-tuple` shape of the scalar in form of two integers tuple (always 1x1)
-
     Notes
     -----
 

diff --git a/python/pyspla/type.py b/python/pyspla/type.py
@@ -45,8 +45,8 @@ class Type:
     """
     Spla base Type for storage parametrization.
 
-    Attributes
-    ----------
+    Binary operations
+    -----------------
 
     PLUS: OpBinary.
         Built-in binary operation associated with a Type.
@@ -87,6 +87,9 @@ class Type:
     BXOR: OpBinary.
         Built-in binary operation associated with a Type. Supported only for integral types.
 
+    Select operations
+    -----------------
+
     EQZERO: OpSelect.
         Built-in selection operation associated with a Type.
 
@@ -151,7 +154,7 @@ class Type:
     @classmethod
     def get_code(cls):
         """
-
+        Literal code of the type in numpy style.
         """
         return cls._code
 

diff --git a/python/pyspla/vector.py b/python/pyspla/vector.py
@@ -33,12 +33,6 @@ class Vector:
     """
     Generalized statically-typed sparse storage-invariant vector primitive.
 
-    Attributes
-    ----------
-
-    - type : `type` type of stored vector elements
-    - shape : `2-tuple` shape of the vector in form of two integers tuple (second dim is 1)
-
     Notes
     -----