[Project] Minor readme && docs fixes/improvements

Author: EgorOrachyov

README.md

@@ -12,8 +12,11 @@ work with sparse matrices written on the NVIDIA CUDA platform. The primary
 goal of the library is implementation, testing and profiling algorithms for
 solving *formal-language-constrained problems*, such as *context-free* 
 and *regular* path queries with various semantics for graph databases.
-The library provides C-compatible API, written in the GraphBLAS style,
-as well as python high-level wrapper with automated resources management and fancy syntax sugar.
+The library provides C-compatible API, written in the GraphBLAS style.
+
+**The library** is shipped with python package **pycubool** - wrapper for
+cuBool library C API. This package exports library features and primitives 
+in high-level format with automated resources management and fancy syntax sugar.
 
 **The primary library primitive** is a sparse boolean matrix. The library provides 
 the most popular operations for matrix manipulation, such as construction from
@@ -34,7 +37,7 @@ prototyping algorithms on a local computer for later running on a powerful serve
 - [X] Sparse matrix element-wise addition
 - [X] Sparse matrix kronecker
 - [X] Sparse matrix transpose
-- [X] Sparse matrix submatrix
+- [X] Sparse matrix extract sub-matrix
 - [X] Sparse matrix reduce
 - [X] Sparse matrix slicing
 - [X] Matrix cached filling
@@ -54,6 +57,13 @@ prototyping algorithms on a local computer for later running on a powerful serve
 - [ ] Publish built artifacts and shared libs
 - [ ] Publish stable source code archives
 
+## Installation
+
+If you running OS **Ubuntu 20.04** or higher you can download the official
+PyPI **pycubool** python package, which includes compiled CPP library source
+with Cuda and Sequential computations supports. Installation process 
+requires only `python3` to be installed on your machine. 
+
 ## Getting Started
 
 ### Requirements
@@ -257,7 +267,8 @@ cuBool
 │   └── tests - gtest-based unit-tests collection
 ├── python - pycubool related source
 │   ├── pycubool - cubool library wrapper for python (similar to pygraphblas)
-│   └── tests - tests for python wrapper
+│   ├── tests - regression tests for python wrapper
+│   └── data - generate data for pycubool regression tests
 ├── deps - project dependencies
 │   ├── cub - cuda utility, required for nsparse
 │   ├── gtest - google test framework for unit testing
@@ -273,6 +284,18 @@ cuBool
 - Pavel Alimov (Github : [Krekep](https://github.com/Krekep))
 - Semyon Grigorev (Github: [gsvgit](https://github.com/gsvgit))
 
+## Citation 
+
+```ignorelang
+@online{cuBool,
+  author = {Orachyov, Egor and Alimov, Pavel and Grigorev, Semyon},
+  title = {cuBool: sparse Boolean linear algebra for Nvidia Cuda},
+  year = 2020,
+  url = {https://github.com/JetBrains-Research/cuBool},
+  note = {Version Alpha}
+}
+```
+
 ## License
 
 This project is licensed under MIT License. License text can be found in the 

docs/logo/cubool_logo_trsp.png

@@ -13,8 +13,11 @@ work with sparse matrices written on the NVIDIA CUDA platform. The primary
 goal of the library is implementation, testing and profiling algorithms for
 solving *formal-language-constrained problems*, such as *context-free* 
 and *regular* path queries with various semantics for graph databases.
-The library provides C-compatible API, written in the GraphBLAS style,
-as well as python high-level wrapper with automated resources management and fancy syntax sugar.
+The library provides C-compatible API, written in the GraphBLAS style.
+
+**The library** is shipped with python package **pycubool** - wrapper for
+cuBool library C API. This package exports library features and primitives 
+in high-level format with automated resources management and fancy syntax sugar.
 
 **The primary library primitive** is a sparse boolean matrix. The library provides 
 the most popular operations for matrix manipulation, such as construction from
@@ -24,7 +27,17 @@ element-wise addition, matrix-matrix multiplication and Kronecker product.
 **As a fallback** library provides sequential backend for mentioned above operations
 for computations on CPU side only. This backend is selected automatically
 if Cuda compatible device is not presented in the system. This can be quite handy for 
-prototyping algorithms on a local computer for later running on a powerful server.  
+prototyping algorithms on a local computer for later running on a powerful server.   
+
+## Sparse Boolean Matrix Features
+
+- Matrix creation (empty, from data, with random data)
+- Matrix-matrix operations (multiplication, element-wise addition, kronecker product)
+- Matrix operations (equality, transpose, reduce to vector, extract sub-matrix)
+- Matrix data extraction (as lists, as list of pairs)
+- Matrix syntax sugar (pretty string printing, slicing, iterating through non-zero values)
+- IO (import/export matrix from/to `.mtx` file format)
+- Debug (matrix string debug markers, logging)
 
 ## Example
 
@@ -60,6 +73,18 @@ def transitive_closure(a: pycubool.Matrix):
 - Pavel Alimov (Github : [Krekep](https://github.com/Krekep))
 - Semyon Grigorev (Github: [gsvgit](https://github.com/gsvgit))
 
+## Citation 
+
+```ignorelang
+@online{cuBool,
+  author = {Orachyov, Egor and Alimov, Pavel and Grigorev, Semyon},
+  title = {cuBool: sparse Boolean linear algebra for Nvidia Cuda},
+  year = 2020,
+  url = {https://github.com/JetBrains-Research/cuBool},
+  note = {Version Alpha}
+}
+```
+
 ## License
 
 This project is licensed under MIT License. License text can be found in the 

python/README.md

@@ -1,3 +1,15 @@
+"""
+cuBool C API Python bridge.
+
+Wraps native C API details for accessing
+this functionality via Python CTypes library.
+
+Functionality:
+- Flags wrapping
+- Functions definitions
+- Error checking
+"""
+
 import ctypes
 
 __all__ = [

python/pycubool/bridge.py

@@ -1,3 +1,8 @@
+"""
+IO operations for exporting/importing mtx data.
+Provides features to import/export data or pycubool matrix in mtx format.
+"""
+
 from . import Matrix
 
 

python/pycubool/io.py

@@ -1,3 +1,7 @@
+"""
+Matrix primitive.
+"""
+
 import ctypes
 import random
 

python/pycubool/matrix.py

@@ -1,3 +1,8 @@
+"""
+cuBool library state wrapper.
+Provides global access points and initialization logic for library API.
+"""
+
 import os
 import ctypes
 import pathlib