[DOC] Refine documentation of runtime feature detection (#14238)

* minor: Refine documentation * Update python/mxnet/runtime.py Co-Authored-By: larroy <[email protected]> * Update python/mxnet/runtime.py Co-Authored-By: larroy <[email protected]> * Address CR comment * retrigger CI
apache · Mar 5, 2019 · 434726e · 434726e
1 parent 780bddc
commit 434726e
Show file tree

Hide file tree

Showing 2 changed files with 77 additions and 23 deletions.
diff --git a/docs/api/python/libinfo/libinfo.md b/docs/api/python/libinfo/libinfo.md
@@ -28,33 +28,74 @@ The libinfo functionality allows to check for compile-time features supported by
 ### Example usage
 
 ```
-In [1]: import mxnet as mx
+In []: import mxnet as mx
    ...: import mxnet.runtime
    ...: fs = mx.runtime.Features()
 
-In [2]: fs
-Out[2]: [✖ CUDA, ✖ CUDNN, ✖ NCCL, ✖ CUDA_RTC, ✖ TENSORRT, ✔ CPU_SSE, ✔ CPU_SSE2, ✔ CPU_SSE3, ✔ CPU_SSE4_1, ✔ CPU_SSE4_2, ✖ CPU_SSE4A, ✔ CPU_AVX, ✖ CPU_AVX2, ✖ OPENMP, ✖ SSE, ✔ F16C, ✖ JEMALLOC, ✔ BLAS_OPEN, ✖ BLAS_ATLAS, ✖ BLAS_MKL, ✖ BLAS_APPLE, ✔ LAPACK, ✖ MKLDNN, ✔ OPENCV, ✖ CAFFE, ✖ PROFILER, ✖ DIST_KVSTORE, ✖ CXX14, ✔ SIGNAL_HANDLER, ✔ DEBUG]
-
-In [3]: fs['CUDA'].enabled
-Out[3]: False
-
-In [4]: fs.is_enabled('CPU_SSE')
-Out[4]: True
-
-In [5]: fs.is_enabled('CUDA')
-Out[5]: False
-
-In [6]:
+In []: fs
+Out[]: [✖ CUDA, ✖ CUDNN, ✖ NCCL, ✖ CUDA_RTC, ✖ TENSORRT, ✔ CPU_SSE, ✔ CPU_SSE2, ✔ CPU_SSE3, ✔ CPU_SSE4_1, ✔ CPU_SSE4_2, ✖ CPU_SSE4A, ✔ CPU_AVX, ✖ CPU_AVX2, ✖ OPENMP, ✖ SSE, ✔ F16C, ✖ JEMALLOC, ✔ BLAS_OPEN, ✖ BLAS_ATLAS, ✖ BLAS_MKL, ✖ BLAS_APPLE, ✔ LAPACK, ✖ MKLDNN, ✔ OPENCV, ✖ CAFFE, ✖ PROFILER, ✖ DIST_KVSTORE, ✖ CXX14, ✔ SIGNAL_HANDLER, ✔ DEBUG]
+
+In []: fs.keys()
+Out[]: odict_keys(['CUDA', 'CUDNN', 'NCCL', 'CUDA_RTC', 'TENSORRT', 'CPU_SSE', 'CPU_SSE2', 'CPU_SSE3', 'CPU_SSE4_1', 'CPU_SSE4_2', 'CPU_SSE4A', 'CPU_AVX', 'CPU_AVX2', 'OPENMP', 'SSE', 'F16C', 'JEMALLOC', 'BLAS_OPEN', 'BLAS_ATLAS', 'BLAS_MKL', 'BLAS_APPLE', 'LAPACK', 'MKLDNN', 'OPENCV', 'CAFFE', 'PROFILER', 'DIST_KVSTORE', 'CXX14', 'SIGNAL_HANDLER', 'DEBUG'])
+
+In []: type(fs['CUDA'])
+Out[]: mxnet.runtime.Feature
+
+In []: fs['CUDA'].enabled
+Out[]: False
+
+In []: fs.is_enabled('CPU_SSE')
+Out[]: True
+
+In []: fs.is_enabled('CUDA')
+Out[]: False
+
+In []: features = mx.runtime.feature_list()
+
+In []: features
+Out[]:
+[✖ CUDA,
+ ✖ CUDNN,
+ ✖ NCCL,
+ ✖ CUDA_RTC,
+ ✖ TENSORRT,
+ ✔ CPU_SSE,
+ ✔ CPU_SSE2,
+ ✔ CPU_SSE3,
+ ✔ CPU_SSE4_1,
+ ✔ CPU_SSE4_2,
+ ✖ CPU_SSE4A,
+ ✔ CPU_AVX,
+ ✖ CPU_AVX2,
+ ✖ OPENMP,
+ ✖ SSE,
+ ✔ F16C,
+ ✖ JEMALLOC,
+ ✔ BLAS_OPEN,
+ ✖ BLAS_ATLAS,
+ ✖ BLAS_MKL,
+ ✖ BLAS_APPLE,
+ ✔ LAPACK,
+ ✖ MKLDNN,
+ ✔ OPENCV,
+ ✖ CAFFE,
+ ✖ PROFILER,
+ ✖ DIST_KVSTORE,
+ ✖ CXX14,
+ ✔ SIGNAL_HANDLER,
+ ✔ DEBUG]
+
+In []: type(features)
+Out[]: list
+
+In []: type(features[0])
+Out[]: mxnet.runtime.Feature
 ```
 
-
 ```eval_rst
 .. autosummary::
     :nosignatures:
 
-    Features
-    Feature
-    feature_list
 ```
 
 ## API Reference

diff --git a/python/mxnet/runtime.py b/python/mxnet/runtime.py
@@ -27,17 +27,27 @@
 
 class Feature(ctypes.Structure):
     """
-    Compile time feature description
+    Compile time feature description, member fields: `name` and `enabled`.
     """
     _fields_ = [
         ("_name", ctypes.c_char_p),
-        ("enabled", ctypes.c_bool)
+        ("_enabled", ctypes.c_bool)
     ]
 
     @property
     def name(self):
+        """
+        Feature name.
+        """
         return self._name.decode()
 
+    @property
+    def enabled(self):
+        """
+        True if MXNet was compiled with the given compile-time feature.
+        """
+        return self._enabled
+
     def __repr__(self):
         if self.enabled:
             return "✔ {}".format(self.name)
@@ -50,7 +60,8 @@ def feature_list():
 
     Returns
     -------
-    :return: list of class LibFeature indicating which features are available and enabled
+    list
+        List of :class:`.Feature` objects
     """
     lib_features_c_array = ctypes.POINTER(Feature)()
     lib_features_size = ctypes.c_size_t()
@@ -74,11 +85,13 @@ def is_enabled(self, feature_name):
 
         Parameters
         ----------
-        :param x: str The name of a valid feature as string for example 'CUDA'
+        feature_name: str
+            The name of a valid feature as string for example 'CUDA'
 
         Returns
         -------
-        :return: bool True if it's enabled, False if it's disabled, RuntimeError if the feature is not known
+        Boolean
+            True if it's enabled, False if it's disabled, RuntimeError if the feature is not known
         """
         feature_name = feature_name.upper()
         if feature_name not in self: