From 2e8ee6d21000a95ff99a20e8d88a13f8a386f454 Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Thu, 10 Aug 2023 21:13:36 +0200 Subject: [PATCH 01/23] Add install with upgrade option when installing latest development package. --- docs/getting_started.in.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting_started.in.rst b/docs/getting_started.in.rst index e3ff7529fa6..a6c2dc2e5df 100644 --- a/docs/getting_started.in.rst +++ b/docs/getting_started.in.rst @@ -100,7 +100,7 @@ install the latest development version directly with pip: .. code-block:: bash - pip install --trusted-host www.open3d.org -f http://www.open3d.org/docs/latest/getting_started.html open3d + pip install -U --trusted-host www.open3d.org -f http://www.open3d.org/docs/latest/getting_started.html open3d .. note:: The development wheels for Linux are named according to PEP600. Please From 86e7a2f2abd36ca81366fd52cd50fc7e048a8e9b Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Thu, 10 Aug 2023 21:14:08 +0200 Subject: [PATCH 02/23] util/install-deps-python.sh was removed in https://github.com/isl-org/Open3D/pull/2146 --- docs/getting_started.in.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/getting_started.in.rst b/docs/getting_started.in.rst index a6c2dc2e5df..ab448443432 100644 --- a/docs/getting_started.in.rst +++ b/docs/getting_started.in.rst @@ -144,9 +144,7 @@ demonstrate the usage of Open3D Python interface. See ``examples/python`` for all Python examples. .. note:: Open3D's Python tutorial utilizes some external packages: ``numpy``, - ``matplotlib``, ``opencv-python``. OpenCV is only used for reconstruction - system. Please read ``util/install-deps-python.sh`` for installing these - packages. + ``matplotlib``, ``opencv-python``. .. _install_open3d_c++: From 3ea347da577d6b537614ab2d00c6c56440477610 Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Fri, 11 Aug 2023 14:06:51 +0200 Subject: [PATCH 03/23] Grammar fix. --- docs/cpp_project.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cpp_project.rst b/docs/cpp_project.rst index ef931912723..89bfd98b70f 100644 --- a/docs/cpp_project.rst +++ b/docs/cpp_project.rst @@ -10,7 +10,7 @@ We provide two example CMake projects to demonstrate how to use Open3D in your CMake projects. * `Find Pre-Installed Open3D Package in CMake `_ - This option can be used if you'd like Open3D build and install Open3D first, + This option can be used if you'd like to build and install Open3D first, then link your project to Open3D. * `Use Open3D as a CMake External Project `_ This option can be used if you'd like Open3D to build alongside with your From 381882df71dd8f8eedd64b2617e6e01fefad3aeb Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Fri, 11 Aug 2023 14:16:04 +0200 Subject: [PATCH 04/23] Move open3d_ml and arm to after docker. --- docs/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 391c0298e64..57c012b33a6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -26,9 +26,9 @@ Open3D: A Modern Library for 3D Data Processing compilation cpp_project builddocs - open3d_ml - arm docker + arm + open3d_ml .. toctree:: :maxdepth: 2 From 17a27a3dce81a01fafff26fc2a85bf1e639e4a2a Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Fri, 11 Aug 2023 14:23:34 +0200 Subject: [PATCH 05/23] organize TOC - Move C++ and Contribution to end and keep python section together. --- docs/index.rst | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 57c012b33a6..ca0da37702d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -46,23 +46,6 @@ Open3D: A Modern Library for 3D Data Processing tutorial/sensor/index tutorial/reference -.. toctree:: - :maxdepth: 1 - :caption: Contribute - - contribute/contribute - contribute/contribution_recipes - contribute/styleguide - -.. toctree:: - :maxdepth: 1 - :caption: C++ API - - cpp_api - -.. - Note: when adding new modules, please also update documented_modules.txt. - .. toctree:: :maxdepth: 1 :caption: Python API @@ -88,3 +71,20 @@ Open3D: A Modern Library for 3D Data Processing python_example/pipelines/index python_example/utility/index python_example/visualization/index + +.. toctree:: + :maxdepth: 1 + :caption: C++ API + + cpp_api + +.. toctree:: + :maxdepth: 1 + :caption: Contribute + + contribute/contribute + contribute/contribution_recipes + contribute/styleguide + +.. + Note: when adding new modules, please also update documented_modules.txt. From 0b8edfdba34f10e68507b9caf055919be9aa8757 Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Fri, 11 Aug 2023 17:07:39 +0200 Subject: [PATCH 06/23] Fix sphinx warnings (Title underline too short). --- docs/make_docs.py | 8 ++++---- docs/tutorial/t_geometry/index.rst | 2 +- docs/tutorial/t_pipelines/index.rst | 2 +- docs/tutorial/t_reconstruction_system/index.rst | 2 +- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/make_docs.py b/docs/make_docs.py index 817898de3eb..413ffa7821b 100644 --- a/docs/make_docs.py +++ b/docs/make_docs.py @@ -305,11 +305,11 @@ def _generate_index(title, output_path): f.write(out_string) @staticmethod - def _add_example_to_docs(example, output_path): + def _add_example_to_docs(example: Path, output_path): shutil.copy(example, output_path) - out_string = (f"{example.stem}.py" - f"\n```````````````````````````````````````\n" - f"\n.. literalinclude:: {example.stem}.py" + out_string = (f"{example.name}" + f"\n{'`' * (len(example.name))}\n" + f"\n.. literalinclude:: {example.name}" f"\n :language: python" f"\n :linenos:" f"\n\n\n") diff --git a/docs/tutorial/t_geometry/index.rst b/docs/tutorial/t_geometry/index.rst index e1f1e9a4bc8..7c24fb565cb 100644 --- a/docs/tutorial/t_geometry/index.rst +++ b/docs/tutorial/t_geometry/index.rst @@ -1,5 +1,5 @@ Geometry (Tensor) -======== +================= .. toctree:: :caption: Basics diff --git a/docs/tutorial/t_pipelines/index.rst b/docs/tutorial/t_pipelines/index.rst index b687d2ce428..b10fa1b0e09 100644 --- a/docs/tutorial/t_pipelines/index.rst +++ b/docs/tutorial/t_pipelines/index.rst @@ -1,7 +1,7 @@ .. _t_pipelines: Pipelines (Tensor) -========= +================== .. toctree:: diff --git a/docs/tutorial/t_reconstruction_system/index.rst b/docs/tutorial/t_reconstruction_system/index.rst index 31322f613c0..5a21ec59140 100644 --- a/docs/tutorial/t_reconstruction_system/index.rst +++ b/docs/tutorial/t_reconstruction_system/index.rst @@ -87,7 +87,7 @@ images using the Intel RealSense camera. For more details, please see :ref:`capture_your_own_dataset`. Getting started with online reconstruction system -`````````````````````````````````````` +````````````````````````````````````````````````` .. toctree:: From 201b6bd10c861bb63b9969e040302a7022e1862b Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Fri, 11 Aug 2023 19:01:50 +0200 Subject: [PATCH 07/23] Fix extra heading drop when going one level down. --- docs/jupyter/t_pipelines/t_icp_registration.ipynb | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/jupyter/t_pipelines/t_icp_registration.ipynb b/docs/jupyter/t_pipelines/t_icp_registration.ipynb index 44a21f39584..cb22159bc7f 100644 --- a/docs/jupyter/t_pipelines/t_icp_registration.ipynb +++ b/docs/jupyter/t_pipelines/t_icp_registration.ipynb @@ -405,7 +405,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "#### 1. Set Inputs and Parameters" + "### 1. Set Inputs and Parameters" ] }, { @@ -453,7 +453,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "#### 2. Get Registration Result from ICP" + "### 2. Get Registration Result from ICP" ] }, { @@ -602,7 +602,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "#### 1. Set Inputs and Parameters" + "### 1. Set Inputs and Parameters" ] }, { @@ -656,7 +656,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "#### 2. Get Registration Result from Multi-Scale ICP" + "### 2. Get Registration Result from Multi-Scale ICP" ] }, { @@ -884,7 +884,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "#### 1. Set Inputs and Parameters" + "### 1. Set Inputs and Parameters" ] }, { From 5d798fd69c448d99d04d925b3b2f09cbd976d376 Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Fri, 11 Aug 2023 19:02:06 +0200 Subject: [PATCH 08/23] Fix cross reference links --- docs/jupyter/visualization/visualization.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/jupyter/visualization/visualization.ipynb b/docs/jupyter/visualization/visualization.ipynb index 63dcf2ed863..9b7030599f6 100644 --- a/docs/jupyter/visualization/visualization.ipynb +++ b/docs/jupyter/visualization/visualization.ipynb @@ -129,7 +129,7 @@ "metadata": {}, "source": [ "## Geometry primitives\n", - "The code below generates a box, a sphere, and a cylinder using `create_box`, `create_sphere`, and `create_cylinder`. The box is painted in red, the sphere is painted in blue, and the cylinder is painted in green. Normals are computed for all meshes to support Phong shading (see [Visualize 3D mesh](mesh.ipynb#visualize-a-3d-mesh) and [Surface normal estimation](mesh.ipynb#surface-normal-estimation)). We can even create a coordinate axis using `create_coordinate_frame`, with its origin point set at (-2, -2, -2)." + "The code below generates a box, a sphere, and a cylinder using `create_box`, `create_sphere`, and `create_cylinder`. The box is painted in red, the sphere is painted in blue, and the cylinder is painted in green. Normals are computed for all meshes to support Phong shading (see [Visualize 3D mesh](../geometry/mesh.ipynb#visualize-a-3d-mesh) and [Surface normal estimation](../geometry/mesh.ipynb#surface-normal-estimation)). We can even create a coordinate axis using `create_coordinate_frame`, with its origin point set at (-2, -2, -2)." ] }, { From 42a1106d191a87ee16ccf7f2440269bfbc1bc872 Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Sat, 12 Aug 2023 16:25:11 +0200 Subject: [PATCH 09/23] Add files/directories to ignore for sphinx, reduces inconsistency warnings. --- docs/conf.in.py | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/conf.in.py b/docs/conf.in.py index 0954849a09b..2a9542c9e54 100644 --- a/docs/conf.in.py +++ b/docs/conf.in.py @@ -27,12 +27,10 @@ # import sys # sys.path.insert(0, os.path.abspath('.')) -import sys import os import re import subprocess -from pathlib import Path -import shutil +import sys def get_git_short_hash(): @@ -120,7 +118,15 @@ def get_git_short_hash(): # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This patterns also effect to html_static_path and html_extra_path -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "**.ipynb_checkpoints"] +exclude_patterns = [ + "_build", + "Thumbs.db", + ".DS_Store", + "**.ipynb_checkpoints", + "docker.in.rst", + "getting_started.in.rst", + "jupyter/*/*.ipynb", +] # The name of the Pygments (syntax highlighting) style to use. pygments_style = "sphinx" From 4c48feb8cff8341905da9696067f26a6096e2ac4 Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Sat, 12 Aug 2023 17:05:01 +0200 Subject: [PATCH 10/23] Fix `Unknown directive type "code_block"` warning. --- docs/tutorial/geometry/uvmaps.rst | 35 +++++++++++++++++++++++-------- 1 file changed, 26 insertions(+), 9 deletions(-) diff --git a/docs/tutorial/geometry/uvmaps.rst b/docs/tutorial/geometry/uvmaps.rst index 7fccce5008f..7d4c7aa7344 100644 --- a/docs/tutorial/geometry/uvmaps.rst +++ b/docs/tutorial/geometry/uvmaps.rst @@ -24,7 +24,8 @@ Quick Reference to default UV Maps for some primitive shapes provided by Open3D The examples below all assume the following code preamble: -.. code_block:: python +.. code-block:: python + import open3d as o3d import open3d.visualization.rendering as rendering @@ -45,7 +46,9 @@ Example Texture Map Box (map uv to each face = false) ************************************ -.. code_block:: python +.. code-block:: python + + box = o3d.geometry.TriangleMesh.create_box(create_uv_map=True) o3d.visualization.draw({'name': 'box', 'geometry': box, 'material': material}) @@ -62,7 +65,9 @@ Box (map uv to each face = false) Box (map uv to each face = true) ************************************** -.. code_block:: python +.. code-block:: python + + box = o3d.geometry.TriangleMesh.create_box(create_uv_map=True, map_texture_to_each_face=True) o3d.visualization.draw({'name': 'box', 'geometry': box, 'material': material}) @@ -80,7 +85,9 @@ Box (map uv to each face = true) Tetrahedral ************* -.. code_block:: python +.. code-block:: python + + tetra = o3d.geometry.TriangleMesh.create_tetrahedron(create_uv_map=True) o3d.visualization.draw({'name': 'tetrahedron', 'geometry': tetra, 'material': material}) @@ -98,7 +105,9 @@ Tetrahedral Octahedral *************** -.. code_block:: python +.. code-block:: python + + octo = o3d.geometry.TriangleMesh.create_octahedron(create_uv_map=True) o3d.visualization.draw({'name': 'octahedron', 'geometry': octo, 'material': material}) @@ -115,7 +124,9 @@ Octahedral Icosahedron ************** -.. code_block:: python +.. code-block:: python + + ico = o3d.geometry.TriangleMesh.create_icosahedron(create_uv_map=True) o3d.visualization.draw({'name': 'icosahedron', 'geometry': ico, 'material': material}) @@ -132,7 +143,9 @@ Icosahedron Cylinder ************* -.. code_block:: python +.. code-block:: python + + cylinder = o3d.geometry.TriangleMesh.create_cylinder(create_uv_map=True) o3d.visualization.draw({'name': 'cylinder', 'geometry': cylinder, 'material': material}) @@ -149,7 +162,9 @@ Cylinder Cone ******* -.. code_block:: python +.. code-block:: python + + cone = o3d.geometry.TriangleMesh.create_cone(create_uv_map=True) o3d.visualization.draw({'name': 'cone', 'geometry': cone, 'material': material}) @@ -166,7 +181,9 @@ Cone Sphere ******* -.. code_block:: python +.. code-block:: python + + sphere = o3d.geometry.TriangleMesh.create_sphere(create_uv_map=True) o3d.visualization.draw({'name': 'sphere', 'geometry': sphere, 'material': material}) From 9af3bdcf2836a64131ab59a5bc6e1df927630832 Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Sat, 12 Aug 2023 17:05:53 +0200 Subject: [PATCH 11/23] Add uvmaps to official docs, fix - `WARNING: document isn't included in any toctree`. --- docs/tutorial/geometry/index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/tutorial/geometry/index.rst b/docs/tutorial/geometry/index.rst index 2cade36c5ed..ea7292387c5 100644 --- a/docs/tutorial/geometry/index.rst +++ b/docs/tutorial/geometry/index.rst @@ -22,6 +22,7 @@ Geometry iss_keypoint_detector ray_casting distance_queries + uvmaps .. toctree:: :caption: Interface From d71cd20eb880594bc91bf4f545d17bc28b1b84c2 Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Sat, 12 Aug 2023 17:29:55 +0200 Subject: [PATCH 12/23] Fix yaml lexer name - See https://pygments.org/languages/ --- docs/tutorial/t_reconstruction_system/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorial/t_reconstruction_system/index.rst b/docs/tutorial/t_reconstruction_system/index.rst index 5a21ec59140..e00d323e410 100644 --- a/docs/tutorial/t_reconstruction_system/index.rst +++ b/docs/tutorial/t_reconstruction_system/index.rst @@ -74,7 +74,7 @@ Example config file for online reconstruction system has been provided in ``examples/python/t_reconstruction_system/default_config.yml``, which looks like the following: .. literalinclude:: ../../../examples/python/t_reconstruction_system/default_config.yml - :language: yml + :language: yaml :lineno-start: 1 :lines: 1- :linenos: From 9c956d28125b1fae633d987eb3a3f9d0753c3b01 Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Sat, 12 Aug 2023 17:30:31 +0200 Subject: [PATCH 13/23] Correct the extension --- docs/contribute/contribution_recipes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contribute/contribution_recipes.rst b/docs/contribute/contribution_recipes.rst index b3ff00c4bfb..03102849214 100644 --- a/docs/contribute/contribution_recipes.rst +++ b/docs/contribute/contribution_recipes.rst @@ -264,7 +264,7 @@ Case 4: When adding a Python tutorial .. note:: When you commit a ipynb notebook file make sure to remove the output cells to keep the commit sizes small. - You can use the script ``docs/jupyter/jupyter_strip_output.sh`` for + You can use the script ``docs/jupyter/jupyter_strip_output.py`` for stripping the output cells of all tutorials. Dos From fb7c71c0e4c2108ddaa0a53f196791db088ab132 Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Sat, 12 Aug 2023 17:33:33 +0200 Subject: [PATCH 14/23] Fix warnings - `Inline substitution_reference start-string without end-string.` This escapes vertical bars in bash tree output in pydocs but doesnt fix rendering in html. --- docs/conf.in.py | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/conf.in.py b/docs/conf.in.py index 2a9542c9e54..6b3570d31fa 100644 --- a/docs/conf.in.py +++ b/docs/conf.in.py @@ -31,6 +31,7 @@ import re import subprocess import sys +from typing import List def get_git_short_hash(): @@ -270,8 +271,22 @@ def skip(app, what, name, obj, would_skip, options): return would_skip +def escape_vertical_bars(app, what, name, obj, options, lines: List[str]): + # Note - Latex docs also contains Vertical Bar, so we + # apply this filtering only to specific classes. + if name in [ + "open3d.data.RedwoodIndoorLivingRoom1", + "open3d.data.RedwoodIndoorLivingRoom2", + "open3d.data.RedwoodIndoorOffice1", + "open3d.data.RedwoodIndoorOffice2", + ]: + for index in range(len(lines)): + lines[index] = lines[index].replace("|", "\|") + + def setup(app): app.connect("autodoc-skip-member", skip) + app.connect("autodoc-process-docstring", escape_vertical_bars) # Add Google analytics app.add_js_file("https://www.googletagmanager.com/gtag/js?id=G-3TQPKGV6Z3", **{'async': 'async'}) From c99fd1b0ad3dc2ab3e8c7581fbf630987be15778 Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Sun, 13 Aug 2023 03:18:57 +0200 Subject: [PATCH 15/23] Minor code refactoring of make_docs.py --- docs/make_docs.py | 57 ++++++++++++++++++++++++++--------------------- 1 file changed, 31 insertions(+), 26 deletions(-) diff --git a/docs/make_docs.py b/docs/make_docs.py index 413ffa7821b..1b935c3de25 100644 --- a/docs/make_docs.py +++ b/docs/make_docs.py @@ -11,20 +11,21 @@ # (3) make.py calls the actual `sphinx-build` import argparse -import subprocess -import sys import importlib -import os import inspect -import shutil +import multiprocessing +import os import re -from pathlib import Path -import nbformat -import nbconvert +import shutil import ssl -import certifi +import subprocess +import sys import urllib.request -import multiprocessing +from pathlib import Path + +import certifi +import nbconvert +import nbformat def _create_or_clear_dir(dir_path): @@ -66,10 +67,10 @@ def __init__(self, output_dir="python_api", input_dir="python_api_in"): self.output_dir = output_dir self.input_dir = input_dir self.module_names = PyAPIDocsBuilder._get_documented_module_names() - print("Generating *.rst Python API docs in directory: %s" % - self.output_dir) def generate_rst(self): + print("Generating *.rst Python API docs in directory: %s" % + self.output_dir) _create_or_clear_dir(self.output_dir) for module_name in self.module_names: @@ -279,8 +280,6 @@ def __init__(self, input_dir, pwd, output_dir="python_example"): sys.path.append(os.path.join(pwd, "..", "python", "tools")) from cli import _get_all_examples_dict self.get_all_examples_dict = _get_all_examples_dict - print("Generating *.rst Python example docs in directory: %s" % - self.output_dir) def _get_examples_dict(self): examples_dict = self.get_all_examples_dict() @@ -318,6 +317,8 @@ def _add_example_to_docs(example: Path, output_path): f.write(out_string) def generate_rst(self): + print("Generating *.rst Python example docs in directory: %s" % + self.output_dir) _create_or_clear_dir(self.output_dir) examples_dict = self._get_examples_dict() @@ -482,22 +483,17 @@ def run(self): # Jupyter notebooks os.environ["CI"] = "true" - # Copy and execute notebooks in the tutorial folder + # Copy from jupyter to the tutorial folder. nb_paths = [] - nb_direct_copy = [ - 'draw_plotly.ipynb', - 'hashmap.ipynb', - 'jupyter_visualization.ipynb', - 't_icp_registration.ipynb', - 'tensor.ipynb', - ] + nb_parent_src = Path(self.current_file_dir) / "jupyter" + nb_parent_dst = Path(self.current_file_dir) / "tutorial" example_dirs = [ - "geometry", "t_geometry", "core", "data", "pipelines", - "visualization", "t_pipelines" + name for name in os.listdir(nb_parent_src) + if os.path.isdir(nb_parent_src / name) ] for example_dir in example_dirs: - in_dir = (Path(self.current_file_dir) / "jupyter" / example_dir) - out_dir = Path(self.current_file_dir) / "tutorial" / example_dir + in_dir = nb_parent_src / example_dir + out_dir = nb_parent_dst / example_dir out_dir.mkdir(parents=True, exist_ok=True) shutil.copy( in_dir.parent / "open3d_tutorial.py", @@ -523,6 +519,15 @@ def run(self): shutil.copytree(in_dir / "images", out_dir / "images") # Execute Jupyter notebooks + # Files that should not be executed. + nb_direct_copy = [ + 'draw_plotly.ipynb', + 'hashmap.ipynb', + 'jupyter_visualization.ipynb', + 't_icp_registration.ipynb', + 'tensor.ipynb', + ] + for nb_path in nb_paths: if nb_path.name in nb_direct_copy: print("[Processing notebook {}, directly copied]".format( @@ -584,7 +589,7 @@ def run(self): action="store_true", default=False, help=("Whether to clean existing notebooks in docs/tutorial. " - "Notebooks are copied from examples/python to docs/tutorial."), + "Notebooks are copied from docs/jupyter to docs/tutorial."), ) parser.add_argument( "--execute_notebooks", From af3ba120b2b0d83ab94022f2bfd20f9feed66d31 Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Sun, 13 Aug 2023 03:22:28 +0200 Subject: [PATCH 16/23] Only copy open3d_tutorial.py once --- docs/make_docs.py | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/make_docs.py b/docs/make_docs.py index 1b935c3de25..48dfb6f6440 100644 --- a/docs/make_docs.py +++ b/docs/make_docs.py @@ -491,14 +491,18 @@ def run(self): name for name in os.listdir(nb_parent_src) if os.path.isdir(nb_parent_src / name) ] + + print(f"Copying {nb_parent_src / 'open3d_tutorial.py'} " + f"to {nb_parent_dst / 'open3d_tutorial.py'}") + shutil.copy( + nb_parent_src / "open3d_tutorial.py", + nb_parent_dst / "open3d_tutorial.py", + ) + for example_dir in example_dirs: in_dir = nb_parent_src / example_dir out_dir = nb_parent_dst / example_dir out_dir.mkdir(parents=True, exist_ok=True) - shutil.copy( - in_dir.parent / "open3d_tutorial.py", - out_dir.parent / "open3d_tutorial.py", - ) if self.clean_notebooks: for nb_out_path in out_dir.glob("*.ipynb"): From 04d879998b704da8bcaf5a5f9e2ab83d9fae030c Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Mon, 14 Aug 2023 18:19:29 +0200 Subject: [PATCH 17/23] Move list of classes to a global variable --- docs/conf.in.py | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/conf.in.py b/docs/conf.in.py index 6b3570d31fa..7f3da2cefcb 100644 --- a/docs/conf.in.py +++ b/docs/conf.in.py @@ -271,15 +271,18 @@ def skip(app, what, name, obj, would_skip, options): return would_skip +ESCAPE_VERTICAL_BAR_IN_CLASSES_DOCS: List[str] = [ + "open3d.data.RedwoodIndoorLivingRoom1", + "open3d.data.RedwoodIndoorLivingRoom2", + "open3d.data.RedwoodIndoorOffice1", + "open3d.data.RedwoodIndoorOffice2", +] + + def escape_vertical_bars(app, what, name, obj, options, lines: List[str]): - # Note - Latex docs also contains Vertical Bar, so we + # Note - Latex docs also contain Vertical Bar, so we # apply this filtering only to specific classes. - if name in [ - "open3d.data.RedwoodIndoorLivingRoom1", - "open3d.data.RedwoodIndoorLivingRoom2", - "open3d.data.RedwoodIndoorOffice1", - "open3d.data.RedwoodIndoorOffice2", - ]: + if name in ESCAPE_VERTICAL_BAR_IN_CLASSES_DOCS: for index in range(len(lines)): lines[index] = lines[index].replace("|", "\|") From 3d82438a27169250047cf03a94d2db728325bdd0 Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Mon, 14 Aug 2023 20:59:11 +0200 Subject: [PATCH 18/23] Use f-strings as requested in PR --- docs/make_docs.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/make_docs.py b/docs/make_docs.py index 48dfb6f6440..8249f66b29e 100644 --- a/docs/make_docs.py +++ b/docs/make_docs.py @@ -69,8 +69,8 @@ def __init__(self, output_dir="python_api", input_dir="python_api_in"): self.module_names = PyAPIDocsBuilder._get_documented_module_names() def generate_rst(self): - print("Generating *.rst Python API docs in directory: %s" % - self.output_dir) + print(f"Generating *.rst Python API docs in directory: " + f"{self.output_dir}") _create_or_clear_dir(self.output_dir) for module_name in self.module_names: @@ -317,8 +317,8 @@ def _add_example_to_docs(example: Path, output_path): f.write(out_string) def generate_rst(self): - print("Generating *.rst Python example docs in directory: %s" % - self.output_dir) + print(f"Generating *.rst Python example docs in directory: " + f"{self.output_dir}") _create_or_clear_dir(self.output_dir) examples_dict = self._get_examples_dict() From 549c7397fee18171d7975441c8c3f5a916657dd7 Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Tue, 15 Aug 2023 13:30:57 +0200 Subject: [PATCH 19/23] Add python_api_in as ignored directory. --- docs/conf.in.py | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/conf.in.py b/docs/conf.in.py index 7f3da2cefcb..e7081bceaca 100644 --- a/docs/conf.in.py +++ b/docs/conf.in.py @@ -127,6 +127,7 @@ def get_git_short_hash(): "docker.in.rst", "getting_started.in.rst", "jupyter/*/*.ipynb", + "python_api_in/*.rst", ] # The name of the Pygments (syntax highlighting) style to use. From 0d675cd2e92f80eaec5ee1027d1cc3bfbc0931ed Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Tue, 15 Aug 2023 13:32:32 +0200 Subject: [PATCH 20/23] Revert all changes made for correcting vertical bar in pydocs --- docs/conf.in.py | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/docs/conf.in.py b/docs/conf.in.py index e7081bceaca..39fd31ad673 100644 --- a/docs/conf.in.py +++ b/docs/conf.in.py @@ -31,7 +31,6 @@ import re import subprocess import sys -from typing import List def get_git_short_hash(): @@ -272,25 +271,8 @@ def skip(app, what, name, obj, would_skip, options): return would_skip -ESCAPE_VERTICAL_BAR_IN_CLASSES_DOCS: List[str] = [ - "open3d.data.RedwoodIndoorLivingRoom1", - "open3d.data.RedwoodIndoorLivingRoom2", - "open3d.data.RedwoodIndoorOffice1", - "open3d.data.RedwoodIndoorOffice2", -] - - -def escape_vertical_bars(app, what, name, obj, options, lines: List[str]): - # Note - Latex docs also contain Vertical Bar, so we - # apply this filtering only to specific classes. - if name in ESCAPE_VERTICAL_BAR_IN_CLASSES_DOCS: - for index in range(len(lines)): - lines[index] = lines[index].replace("|", "\|") - - def setup(app): app.connect("autodoc-skip-member", skip) - app.connect("autodoc-process-docstring", escape_vertical_bars) # Add Google analytics app.add_js_file("https://www.googletagmanager.com/gtag/js?id=G-3TQPKGV6Z3", **{'async': 'async'}) From a3cbf05e418db588072b78147284fd814b136050 Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Tue, 15 Aug 2023 13:34:18 +0200 Subject: [PATCH 21/23] Fix pybind docs with literal block for tree output --- cpp/pybind/data/dataset.cpp | 168 ++++++++++++++++++------------------ 1 file changed, 84 insertions(+), 84 deletions(-) diff --git a/cpp/pybind/data/dataset.cpp b/cpp/pybind/data/dataset.cpp index 9cfcca0293c..b86b40c5464 100644 --- a/cpp/pybind/data/dataset.cpp +++ b/cpp/pybind/data/dataset.cpp @@ -974,28 +974,28 @@ void pybind_redwood_indoor_living_room1(py::module& m) { R"doc(RedwoodIndoorLivingRoom1 (Augmented ICL-NUIM Dataset) Data class for `RedwoodIndoorLivingRoom1`, containing dense point cloud, rgb sequence, clean depth sequence, noisy depth sequence, oni -sequence, and ground-truth camera trajectory. +sequence, and ground-truth camera trajectory. :: -RedwoodIndoorLivingRoom1 -|-- colors -| |-- 00000.jpg -| |-- 00001.jpg -| |-- ... -| '-- 02869.jpg -|-- depth -| |-- 00000.png -| |-- 00001.png -| |-- ... -| '-- 02869.png -|-- depth_noisy -| |-- 00000.png -| |-- 00001.png -| |-- ... -| '-- 02869.png -|-- dist-model.txt -|-- livingroom1.oni -|-- livingroom1-traj.txt -'-- livingroom.ply + RedwoodIndoorLivingRoom1 + |-- colors + | |-- 00000.jpg + | |-- 00001.jpg + | |-- ... + | '-- 02869.jpg + |-- depth + | |-- 00000.png + | |-- 00001.png + | |-- ... + | '-- 02869.png + |-- depth_noisy + | |-- 00000.png + | |-- 00001.png + | |-- ... + | '-- 02869.png + |-- dist-model.txt + |-- livingroom1.oni + |-- livingroom1-traj.txt + '-- livingroom.ply )doc"); dataset.def(py::init(), "data_root"_a = ""); dataset.def_property_readonly("point_cloud_path", @@ -1029,28 +1029,28 @@ void pybind_redwood_indoor_living_room2(py::module& m) { R"doc(RedwoodIndoorLivingRoom2 (Augmented ICL-NUIM Dataset) Data class for `RedwoodIndoorLivingRoom2`, containing dense point cloud, rgb sequence, clean depth sequence, noisy depth sequence, oni -sequence, and ground-truth camera trajectory. +sequence, and ground-truth camera trajectory. :: -RedwoodIndoorLivingRoom2 -|-- colors -| |-- 00000.jpg -| |-- 00001.jpg -| |-- ... -| '-- 02349.jpg -|-- depth -| |-- 00000.png -| |-- 00001.png -| |-- ... -| '-- 02349.png -|-- depth_noisy -| |-- 00000.png -| |-- 00001.png -| |-- ... -| '-- 02349.png -|-- dist-model.txt -|-- livingroom2.oni -|-- livingroom2-traj.txt -'-- livingroom.ply + RedwoodIndoorLivingRoom2 + |-- colors + | |-- 00000.jpg + | |-- 00001.jpg + | |-- ... + | '-- 02349.jpg + |-- depth + | |-- 00000.png + | |-- 00001.png + | |-- ... + | '-- 02349.png + |-- depth_noisy + | |-- 00000.png + | |-- 00001.png + | |-- ... + | '-- 02349.png + |-- dist-model.txt + |-- livingroom2.oni + |-- livingroom2-traj.txt + '-- livingroom.ply )doc"); dataset.def(py::init(), "data_root"_a = ""); dataset.def_property_readonly("point_cloud_path", @@ -1083,28 +1083,28 @@ void pybind_redwood_indoor_office1(py::module& m) { R"doc(RedwoodIndoorOffice1 (Augmented ICL-NUIM Dataset) Data class for `RedwoodIndoorOffice1`, containing dense point cloud, rgb sequence, clean depth sequence, noisy depth sequence, oni -sequence, and ground-truth camera trajectory. +sequence, and ground-truth camera trajectory. :: -RedwoodIndoorOffice1 -|-- colors -| |-- 00000.jpg -| |-- 00001.jpg -| |-- ... -| '-- 02689.jpg -|-- depth -| |-- 00000.png -| |-- 00001.png -| |-- ... -| '-- 02689.png -|-- depth_noisy -| |-- 00000.png -| |-- 00001.png -| |-- ... -| '-- 02689.png -|-- dist-model.txt -|-- office1.oni -|-- office1-traj.txt -'-- office.ply + RedwoodIndoorOffice1 + |-- colors + | |-- 00000.jpg + | |-- 00001.jpg + | |-- ... + | '-- 02689.jpg + |-- depth + | |-- 00000.png + | |-- 00001.png + | |-- ... + | '-- 02689.png + |-- depth_noisy + | |-- 00000.png + | |-- 00001.png + | |-- ... + | '-- 02689.png + |-- dist-model.txt + |-- office1.oni + |-- office1-traj.txt + '-- office.ply )doc"); dataset.def(py::init(), "data_root"_a = ""); dataset.def_property_readonly("point_cloud_path", @@ -1136,28 +1136,28 @@ void pybind_redwood_indoor_office2(py::module& m) { R"doc(RedwoodIndoorOffice2 (Augmented ICL-NUIM Dataset) Data class for `RedwoodIndoorOffice2`, containing dense point cloud, rgb sequence, clean depth sequence, noisy depth sequence, oni -sequence, and ground-truth camera trajectory. +sequence, and ground-truth camera trajectory. :: -RedwoodIndoorOffice2 -|-- colors -| |-- 00000.jpg -| |-- 00001.jpg -| |-- ... -| '-- 02537.jpg -|-- depth -| |-- 00000.png -| |-- 00001.png -| |-- ... -| '-- 02537.png -|-- depth_noisy -| |-- 00000.png -| |-- 00001.png -| |-- ... -| '-- 02537.png -|-- dist-model.txt -|-- office2.oni -|-- office2-traj.txt -'-- office.ply + RedwoodIndoorOffice2 + |-- colors + | |-- 00000.jpg + | |-- 00001.jpg + | |-- ... + | '-- 02537.jpg + |-- depth + | |-- 00000.png + | |-- 00001.png + | |-- ... + | '-- 02537.png + |-- depth_noisy + | |-- 00000.png + | |-- 00001.png + | |-- ... + | '-- 02537.png + |-- dist-model.txt + |-- office2.oni + |-- office2-traj.txt + '-- office.ply )doc"); dataset.def(py::init(), "data_root"_a = ""); dataset.def_property_readonly("point_cloud_path", From e807806e02d3c8829ed0be75e6fa58b9847c4f69 Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Tue, 15 Aug 2023 13:35:52 +0200 Subject: [PATCH 22/23] Fix doxygen docs with code block for tree output --- cpp/open3d/data/Dataset.h | 160 +++++++++++++++++++------------------- 1 file changed, 80 insertions(+), 80 deletions(-) diff --git a/cpp/open3d/data/Dataset.h b/cpp/open3d/data/Dataset.h index 97b7ea9fd8f..6e4db556be7 100644 --- a/cpp/open3d/data/Dataset.h +++ b/cpp/open3d/data/Dataset.h @@ -723,26 +723,26 @@ class PaintedPlasterTexture : public DownloadDataset { /// cloud, rgb sequence, clean depth sequence, noisy depth sequence, oni /// sequence, and ground-truth camera trajectory. /// -/// RedwoodIndoorLivingRoom1 -/// ├── colors -/// │ ├── 00000.jpg -/// │ ├── 00001.jpg -/// │ ├── ... -/// │ └── 02869.jpg -/// ├── depth -/// │ ├── 00000.png -/// │ ├── 00001.png -/// │ ├── ... -/// │ └── 02869.png -/// ├── depth_noisy -/// │ ├── 00000.png -/// │ ├── 00001.png -/// │ ├── ... -/// │ └── 02869.png -/// ├── dist-model.txt -/// ├── livingroom1.oni -/// ├── livingroom1-traj.txt -/// └── livingroom.ply +/// RedwoodIndoorLivingRoom1 +/// ├── colors +/// │ ├── 00000.jpg +/// │ ├── 00001.jpg +/// │ ├── ... +/// │ └── 02869.jpg +/// ├── depth +/// │ ├── 00000.png +/// │ ├── 00001.png +/// │ ├── ... +/// │ └── 02869.png +/// ├── depth_noisy +/// │ ├── 00000.png +/// │ ├── 00001.png +/// │ ├── ... +/// │ └── 02869.png +/// ├── dist-model.txt +/// ├── livingroom1.oni +/// ├── livingroom1-traj.txt +/// └── livingroom.ply class RedwoodIndoorLivingRoom1 : public DownloadDataset { public: RedwoodIndoorLivingRoom1(const std::string& data_root = ""); @@ -779,26 +779,26 @@ class RedwoodIndoorLivingRoom1 : public DownloadDataset { /// cloud, rgb sequence, clean depth sequence, noisy depth sequence, oni /// sequence, and ground-truth camera trajectory. /// -/// RedwoodIndoorLivingRoom2 -/// ├── colors -/// │ ├── 00000.jpg -/// │ ├── 00001.jpg -/// │ ├── ... -/// │ └── 02349.jpg -/// ├── depth -/// │ ├── 00000.png -/// │ ├── 00001.png -/// │ ├── ... -/// │ └── 02349.png -/// ├── depth_noisy -/// │ ├── 00000.png -/// │ ├── 00001.png -/// │ ├── ... -/// │ └── 02349.png -/// ├── dist-model.txt -/// ├── livingroom2.oni -/// ├── livingroom2-traj.txt -/// └── livingroom.ply +/// RedwoodIndoorLivingRoom2 +/// ├── colors +/// │ ├── 00000.jpg +/// │ ├── 00001.jpg +/// │ ├── ... +/// │ └── 02349.jpg +/// ├── depth +/// │ ├── 00000.png +/// │ ├── 00001.png +/// │ ├── ... +/// │ └── 02349.png +/// ├── depth_noisy +/// │ ├── 00000.png +/// │ ├── 00001.png +/// │ ├── ... +/// │ └── 02349.png +/// ├── dist-model.txt +/// ├── livingroom2.oni +/// ├── livingroom2-traj.txt +/// └── livingroom.ply class RedwoodIndoorLivingRoom2 : public DownloadDataset { public: RedwoodIndoorLivingRoom2(const std::string& data_root = ""); @@ -835,26 +835,26 @@ class RedwoodIndoorLivingRoom2 : public DownloadDataset { /// cloud, rgb sequence, clean depth sequence, noisy depth sequence, oni /// sequence, and ground-truth camera trajectory. /// -/// RedwoodIndoorOffice1 -/// ├── colors -/// │ ├── 00000.jpg -/// │ ├── 00001.jpg -/// │ ├── ... -/// │ └── 02689.jpg -/// ├── depth -/// │ ├── 00000.png -/// │ ├── 00001.png -/// │ ├── ... -/// │ └── 02689.png -/// ├── depth_noisy -/// │ ├── 00000.png -/// │ ├── 00001.png -/// │ ├── ... -/// │ └── 02689.png -/// ├── dist-model.txt -/// ├── office1.oni -/// ├── office1-traj.txt -/// └── office.ply +/// RedwoodIndoorOffice1 +/// ├── colors +/// │ ├── 00000.jpg +/// │ ├── 00001.jpg +/// │ ├── ... +/// │ └── 02689.jpg +/// ├── depth +/// │ ├── 00000.png +/// │ ├── 00001.png +/// │ ├── ... +/// │ └── 02689.png +/// ├── depth_noisy +/// │ ├── 00000.png +/// │ ├── 00001.png +/// │ ├── ... +/// │ └── 02689.png +/// ├── dist-model.txt +/// ├── office1.oni +/// ├── office1-traj.txt +/// └── office.ply class RedwoodIndoorOffice1 : public DownloadDataset { public: RedwoodIndoorOffice1(const std::string& data_root = ""); @@ -891,26 +891,26 @@ class RedwoodIndoorOffice1 : public DownloadDataset { /// cloud, rgb sequence, clean depth sequence, noisy depth sequence, oni /// sequence, and ground-truth camera trajectory. /// -/// RedwoodIndoorOffice2 -/// ├── colors -/// │ ├── 00000.jpg -/// │ ├── 00001.jpg -/// │ ├── ... -/// │ └── 02537.jpg -/// ├── depth -/// │ ├── 00000.png -/// │ ├── 00001.png -/// │ ├── ... -/// │ └── 02537.png -/// ├── depth_noisy -/// │ ├── 00000.png -/// │ ├── 00001.png -/// │ ├── ... -/// │ └── 02537.png -/// ├── dist-model.txt -/// ├── office2.oni -/// ├── office2-traj.txt -/// └── office.ply +/// RedwoodIndoorOffice2 +/// ├── colors +/// │ ├── 00000.jpg +/// │ ├── 00001.jpg +/// │ ├── ... +/// │ └── 02537.jpg +/// ├── depth +/// │ ├── 00000.png +/// │ ├── 00001.png +/// │ ├── ... +/// │ └── 02537.png +/// ├── depth_noisy +/// │ ├── 00000.png +/// │ ├── 00001.png +/// │ ├── ... +/// │ └── 02537.png +/// ├── dist-model.txt +/// ├── office2.oni +/// ├── office2-traj.txt +/// └── office.ply class RedwoodIndoorOffice2 : public DownloadDataset { public: RedwoodIndoorOffice2(const std::string& data_root = ""); From cfd570f3e5aa801dd2b09adb0dd47b94f08f07be Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Tue, 15 Aug 2023 13:39:19 +0200 Subject: [PATCH 23/23] Correct class names in doxygen docs for RedWood dataset --- cpp/open3d/data/Dataset.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/cpp/open3d/data/Dataset.h b/cpp/open3d/data/Dataset.h index 6e4db556be7..417e3515dce 100644 --- a/cpp/open3d/data/Dataset.h +++ b/cpp/open3d/data/Dataset.h @@ -775,7 +775,7 @@ class RedwoodIndoorLivingRoom1 : public DownloadDataset { }; /// \class RedwoodIndoorLivingRoom2 (Augmented ICL-NUIM Dataset) -/// \brief Data class for `RedwoodIndoorLivingRoom1`, containing dense point +/// \brief Data class for `RedwoodIndoorLivingRoom2`, containing dense point /// cloud, rgb sequence, clean depth sequence, noisy depth sequence, oni /// sequence, and ground-truth camera trajectory. /// @@ -831,7 +831,7 @@ class RedwoodIndoorLivingRoom2 : public DownloadDataset { }; /// \class RedwoodIndoorOffice1 (Augmented ICL-NUIM Dataset) -/// \brief Data class for `RedwoodIndoorLivingRoom1`, containing dense point +/// \brief Data class for `RedwoodIndoorOffice1`, containing dense point /// cloud, rgb sequence, clean depth sequence, noisy depth sequence, oni /// sequence, and ground-truth camera trajectory. /// @@ -887,7 +887,7 @@ class RedwoodIndoorOffice1 : public DownloadDataset { }; /// \class RedwoodIndoorOffice2 (Augmented ICL-NUIM Dataset) -/// \brief Data class for `RedwoodIndoorLivingRoom1`, containing dense point +/// \brief Data class for `RedwoodIndoorOffice2`, containing dense point /// cloud, rgb sequence, clean depth sequence, noisy depth sequence, oni /// sequence, and ground-truth camera trajectory. ///