Fix documentation (#274)

* Fix docs Signed-off-by: Jean-Francois Lafleche <jlafleche@nvidia.com> * Remove unnecessary mock imports Signed-off-by: Jean-Francois Lafleche <jlafleche@nvidia.com>
NVIDIAGameWorks · Jun 5, 2020 · 8de7d64 · 8de7d64
1 parent 4e6e695
commit 8de7d64
Show file tree

Hide file tree

Showing 14 changed files with 83 additions and 77 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -21,7 +21,7 @@
             kal_version = row.split("'")[-2]
             break
 
-sys.path.append('../')
+# sys.path.append('../')
 sys.path.append(os.path.abspath(os.path.join(
     os.path.dirname(__file__), '..', 'kaolin')))
 # import sphinx_rtd_theme
@@ -65,7 +65,9 @@
                         'kaolin.cuda.three_nn',
                         'kaolin.cuda.tri_distance',
                         'kaolin.cuda.mesh_intersection',
-                        'kaolin.graphics.nmr.cuda.rasterize_cuda']
+                        'kaolin.graphics.nmr.cuda.rasterize_cuda',
+                        'kaolin.graphics.softras.soft_rasterize_cuda',
+                        'kaolin.graphics.dib_renderer.cuda.rasterizer']
 
 
 # Add any paths that contain templates here, relative to this directory.

diff --git a/docs/modules/graphics.rst b/docs/modules/graphics.rst
@@ -3,10 +3,9 @@ kaolin.graphics
 
 .. currentmodule:: kaolin.graphics
 
-.. autoclass:: graphics.DifferentiableRenderer
-.. autoclass:: graphics.NeuralMeshRenderer
-.. autoclass:: graphics.SoftRenderer
-.. autoclass:: graphics.DIBRenderer
-.. autofunction:: graphics.Lighting.apply_ambient_light
-.. autofunction:: graphics.Lighting.apply_directional_light
-.. autofunction:: graphics.Transformations.get_eye_from_spherical_coords
+.. autoclass:: kaolin.graphics.DifferentiableRenderer
+.. autoclass:: kaolin.graphics.NeuralMeshRenderer
+.. autoclass:: kaolin.graphics.SoftRenderer
+.. autoclass:: kaolin.graphics.DIBRenderer
+.. autofunction:: kaolin.graphics.Lighting.apply_ambient_light
+.. autofunction:: kaolin.graphics.Lighting.apply_directional_light
diff --git a/kaolin/datasets/base.py b/kaolin/datasets/base.py
@@ -45,9 +45,10 @@ def __new__(metacls, cls_name, base_cls, class_dict):
             - 'cache_dir': path to the cached preprocessed data.
             - 'num_workers': number of process used in parallel for preprocessing (default: number of cores)
         preprocessing_transform (Callable): Called on the outputs of _get_data over the indices
-                                            from 0 to len(self) during the construction of the dataset,
-                                            the preprocessed outputs are then cached to 'cache_dir'.
+            from 0 to len(self) during the construction of the dataset,
+            the preprocessed outputs are then cached to 'cache_dir'.
         transform (Callable): Called on the preprocessed data at __getitem__.
+
         no_progress (bool): disable tqdm progress bar for preprocessing."""
         return type.__new__(metacls, cls_name, base_cls, class_dict)
 

diff --git a/kaolin/datasets/modelnet.py b/kaolin/datasets/modelnet.py
@@ -27,10 +27,8 @@ class ModelNet(KaolinDataset):
 
     Args:
         root (str): Path to the base directory of the ModelNet dataset.
-        split (str, optional): Split to load ('train' vs 'test',
-            default: 'train').
-        categories (iterable, optional): List of categories to load
-            (default: ['chair']).
+        split (str, optional): Split to load ('train' vs 'test', default: 'train').
+        categories (iterable, optional): List of categories to load (default: ['chair']).
 
     Examples:
         >>> dataset = ModelNet(root='data/ModelNet')
@@ -45,10 +43,8 @@ def initialize(self, root: str,
 
         Args:
             root (str): Path to the base directory of the ModelNet dataset.
-            split (str, optional): Split to load ('train' vs 'test',
-                default: 'train').
-            categories (iterable, optional): List of categories to load
-                (default: ['chair']).
+            split (str, optional): Split to load ('train' vs 'test', default: 'train').
+            categories (iterable, optional): List of categories to load (default: ['chair']).
         """
 
         assert split.lower() in ['train', 'test']

diff --git a/kaolin/datasets/shapenet.py b/kaolin/datasets/shapenet.py
@@ -87,6 +87,7 @@ def _convert_categories(categories):
 
 class ShapeNet_Meshes(data.Dataset):
     r"""ShapeNet Dataset class for meshes.
+
     Args:
         root (str): Path to the root directory of the ShapeNet dataset.
         categories (str): List of categories to load from ShapeNet. This list may

diff --git a/kaolin/datasets/shrec.py b/kaolin/datasets/shrec.py
@@ -37,6 +37,7 @@ class SHREC16(KaolinDataset):
             are loaded by default.
         train (bool): If True, return the train split, else return the test
             split (default: True).
+
     Returns:
         .. code-block::
 
@@ -47,12 +48,9 @@ class SHREC16(KaolinDataset):
 
         path: The filepath to the .obj file on disk.
         category: A human-readable string describing the loaded sample.
-        label: An integer (in the range :math:`[0, \text{len(categories)}]`)
-            and can be used for training classifiers for example.
-        vertices: Vertices of the loaded mesh (:math:`(*, 3)`), where :math:`*`
-            indicates a positive integer.
-        faces: Faces of the loaded mesh (:math:`(*, 3)`), where :math:`*`
-            indicates a positive integer.
+        label: An integer (in the range :math:`[0, \text{len(categories)}]`) and can be used for training classifiers for example.
+        vertices: Vertices of the loaded mesh (:math:`(*, 3)`), where :math:`*` indicates a positive integer.
+        faces: Faces of the loaded mesh (:math:`(*, 3)`), where :math:`*` indicates a positive integer.
 
     Example:
         >>> dataset = SHREC16(root='/path/to/SHREC16/', categories=['alien', 'ants'], train=False)

diff --git a/kaolin/graphics/DifferentiableRenderer.py b/kaolin/graphics/DifferentiableRenderer.py
@@ -25,6 +25,7 @@ class DifferentiableRenderer(torch.nn.Module):
     A differentiable renderer takes in vertex geometry, faces (usually
     triangles), and optionally texture (and any other information
     deemed relevant), and implements the following main steps.
+
         * Lighting (ambient and optionally, directional lighting, i.e.,
           diffuse/Lambertian reflection, and optionally specular reflection)
         * (Vertex) Shading (Gouraud/Phong/etc.)

diff --git a/kaolin/graphics/SoftRenderer.py b/kaolin/graphics/SoftRenderer.py
@@ -59,6 +59,7 @@ class SoftRenderer(DifferentiableRenderer):
         If you use this code, please cite the original paper in addition to Kaolin.
 
         .. code-block::
+
             @article{liu2019softras,
               title={Soft Rasterizer: A Differentiable Renderer for Image-based 3D Reasoning},
               author={Liu, Shichen and Li, Tianye and Chen, Weikai and Li, Hao},

diff --git a/kaolin/metrics/mesh.py b/kaolin/metrics/mesh.py
@@ -79,20 +79,21 @@ def forward(self, points, verts_1, verts_2, verts_3):
 def chamfer_distance(mesh1: Mesh, mesh2: Mesh,
                      w1: float = 1., w2: float = 1., num_points=3000):
     r""" computes the chamfer distance bewteen two meshes by sampling the two surfaces
+
     Args:
-            mesh1: (Mesh): first mesh
-            mesh2: (Mesh): second mesh
-            w1: (float): weighting of forward direction
-            w2: (float): weighting of backward direction
-            num_points: number of points to sample on each mesh
+        mesh1 (Mesh): first mesh
+        mesh2 (Mesh): second mesh
+        w1 (float): weighting of forward direction
+        w2 (float): weighting of backward direction
+        num_points (int): number of points to sample on each mesh
 
     Returns:
-            chamfer_distance (torch.Tensor): chamfer distance
+        chamfer_distance (torch.Tensor): chamfer distance
 
     Example:
-            >>> mesh1 = TriangleMesh.from_obj(file1)
-            >>> mesh2 = TriangleMesh.from_obj(file2)
-            >>> distance = chamfer_distance(mesh1, mesh2, 500)
+        >>> mesh1 = TriangleMesh.from_obj(file1)
+        >>> mesh2 = TriangleMesh.from_obj(file2)
+        >>> distance = chamfer_distance(mesh1, mesh2, 500)
 
     """
 
@@ -105,14 +106,14 @@ def edge_length(mesh: Mesh):
     r"""Returns the average length of a face in a mesh
 
     Args:
-            mesh (Mesh): mesh over which to calcuale edge length
+        mesh (Mesh): mesh over which to calcuale edge length
 
     Returns:
-            edge_length (torch.Tensor): averge lenght of mesh edge
+        edge_length (torch.Tensor): averge lenght of mesh edge
 
     Example:
-            >>> mesh  = TriangleMesh.from_obj(file)
-            >>> length = edge_length(mesh)
+        >>> mesh  = TriangleMesh.from_obj(file)
+        >>> length = edge_length(mesh)
 
     """
 
@@ -136,18 +137,18 @@ def laplacian_loss(mesh1: Mesh, mesh2: Mesh):
     r"""Returns the change in laplacian over two meshes
 
     Args:
-            mesh1 (Mesh): first mesh
-            mesh2: (Mesh): second mesh
+        mesh1 (Mesh): first mesh
+        mesh2: (Mesh): second mesh
 
 
     Returns:
-            lap_loss (torch.Tensor):  laplacian change over the mesh
+        lap_loss (torch.Tensor):  laplacian change over the mesh
 
     Example:
-            >>> mesh1 = TriangleMesh.from_obj(file)
-            >>> mesh2 = TriangleMesh.from_obj(file)
-            >>> mesh2.vertices = mesh2.vertices * 1.05
-            >>> lap = laplacian_loss(mesh1, mesh2)
+        >>> mesh1 = TriangleMesh.from_obj(file)
+        >>> mesh2 = TriangleMesh.from_obj(file)
+        >>> mesh2.vertices = mesh2.vertices * 1.05
+        >>> lap = laplacian_loss(mesh1, mesh2)
 
     """
 
@@ -161,16 +162,16 @@ def point_to_surface(points: torch.Tensor, mesh: Mesh):
     r"""Computes the minimum distances from a set of points to a mesh
 
     Args:
-            points (torch.Tensor): set of points
-            mesh (Mesh): mesh to calculate distance
+        points (torch.Tensor): set of points
+        mesh (Mesh): mesh to calculate distance
 
     Returns:
-            distance: mean distance between points and surface
+        distance: mean distance between points and surface
 
     Example:
-            >>> mesh = TriangleMesh.from_obj(file)
-            >>> points = torch.rand(1000,3)
-            >>> loss = point_to_surface(points, mesh)
+        >>> mesh = TriangleMesh.from_obj(file)
+        >>> points = torch.rand(1000,3)
+        >>> loss = point_to_surface(points, mesh)
 
     """
 

diff --git a/kaolin/models/PointNet.py b/kaolin/models/PointNet.py
@@ -28,7 +28,7 @@ class PointNetFeatureExtractor(nn.Module):
     .. note::
 
         If you use this code, please cite the original paper in addition to Kaolin.
-        
+
         .. code-block::
 
             @article{qi2016pointnet,
@@ -203,7 +203,7 @@ class PointNetClassifier(nn.Module):
     .. note::
 
         If you use this code, please cite the original paper in addition to Kaolin.
-        
+
         .. code-block::
 
             @article{qi2016pointnet,
@@ -229,7 +229,7 @@ class PointNetClassifier(nn.Module):
             layers in the feature extractor is implicitly parsed from
             this variable.
         activation (function): Nonlinearity to be used as activation
-                    function after each batchnorm (default: F.relu)
+            function after each batchnorm (default: F.relu)
         batchnorm (bool): Whether or not to use batchnorm layers
             (default: True)
         transposed_input (bool): Whether the input's second and third dimension
@@ -239,12 +239,12 @@ class PointNetClassifier(nn.Module):
 
     Example:
 
-        pointnet = PointNetClassifier(in_channels=6, feat_size=1024,
-                                      feat_layer_dims=[32, 64, 256],
+        >>> pointnet = PointNetClassifier(in_channels=6, feat_size=1024, \
+                                      feat_layer_dims=[32, 64, 256], \
                                       classifier_layer_dims=[500, 200, 100])
-        x = torch.rand(5, 6, 30)
-        y = pointnet(x)
-        print(y.shape)
+        >>> x = torch.rand(5, 6, 30)
+        >>> y = pointnet(x)
+        >>> print(y.shape)
 
     """
 
@@ -368,7 +368,7 @@ class PointNetSegmenter(nn.Module):
     .. note::
 
         If you use this code, please cite the original paper in addition to Kaolin.
-        
+
         .. code-block::
 
             @article{qi2016pointnet,
@@ -394,7 +394,7 @@ class PointNetSegmenter(nn.Module):
             layers in the feature extractor is implicitly parsed from
             this variable.
         activation (function): Nonlinearity to be used as activation
-                    function after each batchnorm (default: F.relu)
+            function after each batchnorm (default: F.relu)
         batchnorm (bool): Whether or not to use batchnorm layers
             (default: True)
         transposed_input (bool): Whether the input's second and third dimension
@@ -404,12 +404,12 @@ class PointNetSegmenter(nn.Module):
 
     Example:
 
-        pointnet = PointNetSegmenter(in_channels=6, feat_size=1024,
-                                         feat_layer_dims=[32, 64, 256],
+        >>> pointnet = PointNetSegmenter(in_channels=6, feat_size=1024, \
+                                         feat_layer_dims=[32, 64, 256], \
                                          classifier_layer_dims=[500, 200, 100])
-        x = torch.rand(5, 6, 30)
-        y = pointnet(x)
-        print(y.shape)
+        >>> x = torch.rand(5, 6, 30)
+        >>> y = pointnet(x)
+        >>> print(y.shape)
 
     """
 

diff --git a/kaolin/rep/Mesh.py b/kaolin/rep/Mesh.py
@@ -589,12 +589,17 @@ def compute_adjacency_info(vertices: torch.Tensor, faces: torch.Tensor):
         a homogeneous mesh, i.e., each face has the same number of vertices.
 
         The outputs have the following format: AA, AA_count
-        AA_count: [count_0, ..., count_n]
+
+        AA_count: ``[count_0, ..., count_n]``
+
         with AA:
-        [[aa_{0,0}, ..., aa_{0,count_0} (, -1, ..., -1)],
-         [aa_{1,0}, ..., aa_{1,count_1} (, -1, ..., -1)],
-                    ...
-         [aa_{n,0}, ..., aa_{n,count_n} (, -1, ..., -1)]]
+
+        .. code-block::
+
+            [[aa_{0,0}, ..., aa_{0,count_0} (, -1, ..., -1)],
+            [aa_{1,0}, ..., aa_{1,count_1} (, -1, ..., -1)],
+                        ...
+            [aa_{n,0}, ..., aa_{n,count_n} (, -1, ..., -1)]]
         """
 
         device = vertices.device

diff --git a/kaolin/rep/QuadMesh.py b/kaolin/rep/QuadMesh.py
@@ -108,8 +108,7 @@ def sample(self, num_samples: int):
 
             Returns:
                 points (torch.Tensor): uniformly sampled points
-                face_choices (torch.Tensor): the face idexes which each point
-                    corresponds to.
+                face_choices (torch.Tensor): the face indexes which each point corresponds to.
 
             Example:
                 >>> points, chosen_faces = mesh.sample(10)

diff --git a/kaolin/transforms/transforms.py b/kaolin/transforms/transforms.py
@@ -110,10 +110,10 @@ class CacheCompose(Transform):
     If the pipeline is already cached, data is returned from disk,
     otherwise, data is converted following the provided transforms.
 
-        Args:
-            transforms (Iterable): List of transforms to compose.
-            cache_dir (str): Directory where objects will be cached. Default
-                             to 'cache'.
+    Args:
+        transforms (Iterable): List of transforms to compose.
+        cache_dir (str): Directory where objects will be cached. Default
+                            to 'cache'.
     """
 
     __ignored_params__ = ['cache_dir', 'cached_ids']

diff --git a/setup.py b/setup.py
@@ -146,6 +146,8 @@ def get_extensions():
 
     # If building with readthedocs, don't compile CUDA extensions
     if os.getenv('READTHEDOCS') != 'True':
+        # For every cuda extension, ensure that their is a corresponding function in
+        # docs/conf.py under `autodoc_mock_imports`.
         cuda_extensions = [
             KaolinCUDAExtension('kaolin.cuda.load_textures', [
                 'kaolin/cuda/load_textures_cuda.cpp',