From 4b583c8ba9daff7af6603691a1912f6bd178e73a Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Sat, 4 Nov 2023 03:54:19 +0100 Subject: [PATCH 01/14] Move conf.in.py to conf.py. --- docs/{conf.in.py => conf.py} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{conf.in.py => conf.py} (100%) diff --git a/docs/conf.in.py b/docs/conf.py similarity index 100% rename from docs/conf.in.py rename to docs/conf.py From c5da6aa26b095d06578ee0ae56d9469556542fb7 Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Sat, 4 Nov 2023 14:33:08 +0100 Subject: [PATCH 02/14] Upgrade all docs dependencies and replace open3d_sphinx_theme with sphinx_rtd_theme --- docs/CMakeLists.txt | 19 ------------------- docs/_templates/versions.html | 20 ++++++++++++++++++++ docs/conf.py | 24 +++++++++--------------- docs/requirements.txt | 14 +++++++------- 4 files changed, 36 insertions(+), 41 deletions(-) create mode 100644 docs/_templates/versions.html diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 564546e58a0..b7565cd95c2 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -4,22 +4,3 @@ configure_file(${CMAKE_CURRENT_SOURCE_DIR}/getting_started.in.rst ${CMAKE_CURRENT_SOURCE_DIR}/getting_started.rst @ONLY) configure_file(${CMAKE_CURRENT_SOURCE_DIR}/docker.in.rst ${CMAKE_CURRENT_SOURCE_DIR}/docker.rst @ONLY) - -include(FetchContent) - -FetchContent_Declare( - ext_open3d_sphinx_theme - PREFIX open3d_sphinx_theme - URL https://github.com/isl-org/open3d_sphinx_theme/archive/c71d2728eb5afd1aeeb20dc27a5a0d42bb402d83.tar.gz - URL_HASH SHA256=98af8b7fdb75a74280b6187dbb58ea601db978d4f3f8956d3d87c59c20786f73 - DOWNLOAD_DIR "${OPEN3D_THIRD_PARTY_DOWNLOAD_DIR}/open3d_sphinx_theme" -) - -if(NOT ext_open3d_sphinx_theme_POPULATED) - FetchContent_Populate(ext_open3d_sphinx_theme) - - set(OPEN3D_SPHINX_THEME_SOURCE_DIR ${ext_open3d_sphinx_theme_SOURCE_DIR}) -endif() - -configure_file(${CMAKE_CURRENT_SOURCE_DIR}/conf.in.py - ${CMAKE_CURRENT_SOURCE_DIR}/conf.py @ONLY) diff --git a/docs/_templates/versions.html b/docs/_templates/versions.html new file mode 100644 index 00000000000..b660cd44101 --- /dev/null +++ b/docs/_templates/versions.html @@ -0,0 +1,20 @@ +{% if display_all_docs_versions %} +{# Add rst-badge after rst-versions for small badge style. #} +
+ + Docs version + {{ version }} + + + + +
+
+
{{ _('Versions') }}
+
    + +
+
+
+
+{% endif %} \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 82a791e42b2..079d20bc2f0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -68,7 +68,8 @@ def get_git_short_hash(): "sphinx.ext.napoleon", "sphinx.ext.todo", "nbsphinx", - 'm2r2', + "m2r2", + "sphinx_rtd_theme", ] if os.environ.get("skip_notebooks", "false") == "true": @@ -139,17 +140,12 @@ def get_git_short_hash(): # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -# -# html_theme = 'alabaster' -theme_path = "@OPEN3D_SPHINX_THEME_SOURCE_DIR@" html_theme = "sphinx_rtd_theme" -html_theme_path = [theme_path] html_favicon = "_static/open3d_logo.ico" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -# html_theme_options = { # 'display_version': True } @@ -159,15 +155,13 @@ def get_git_short_hash(): # so a file named "default.css" will overwrite the builtin "default.css". # '_static' contains the theme overwrite -static_path = os.path.join(theme_path, "sphinx_rtd_theme", "static") -html_static_path = [static_path, "_static"] - -# Force table wrap: https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html -html_context = { - "css_files": [ - "_static/theme_overrides.css" # override wide tables in RTD theme - ] -} +html_static_path = ["_static"] + +# Display selection of all documentation versions. +html_context = {'display_all_docs_versions': True} + +# Override theme css +html_css_files = ["theme_overrides.css"] # added by Jaesik to hide "View page source" html_show_sourcelink = False diff --git a/docs/requirements.txt b/docs/requirements.txt index 5475bcd5392..3836800a8a7 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,7 +1,7 @@ -sphinx==3.3.1 -sphinx-rtd-theme==0.5.2 -nbsphinx==0.8.3 -matplotlib==3.3.3 -jinja2==3.0.3 -m2r2==0.2.7 -mistune==0.8.4 +sphinx==7.1.2 +sphinx-rtd-theme==1.3.0 +nbsphinx==0.9.3 +matplotlib==3.7.3 +jinja2==3.1.2 +m2r2==0.3.2 +mistune==0.8.4 \ No newline at end of file From d813f3b1e14b2f8704e38c895351f6a580cdb056 Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Sat, 4 Nov 2023 20:05:20 +0100 Subject: [PATCH 03/14] Lower docutils to version 0.17.0 and sort dependencies --- docs/requirements.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index 3836800a8a7..e8ca97234c5 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,7 +1,7 @@ -sphinx==7.1.2 -sphinx-rtd-theme==1.3.0 -nbsphinx==0.9.3 -matplotlib==3.7.3 +docutils==0.17.0 jinja2==3.1.2 m2r2==0.3.2 -mistune==0.8.4 \ No newline at end of file +matplotlib==3.7.3 +nbsphinx==0.9.3 +sphinx==5.3.0 +sphinx-rtd-theme==1.3.0 From e3a5d389880451a881a23e36293c9835628734d4 Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Sat, 4 Nov 2023 21:03:19 +0100 Subject: [PATCH 04/14] Fix CI badges. --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index ea43c38ffca..22c191ca789 100644 --- a/README.md +++ b/README.md @@ -24,9 +24,9 @@ data structures and algorithms in both C++ and Python. The backend is highly optimized and is set up for parallelization. We welcome contributions from the open-source community. -[![Ubuntu CI](https://github.com/isl-org/Open3D/workflows/Ubuntu%20CI/badge.svg)](https://github.com/isl-org/Open3D/actions?query=workflow%3A%22Ubuntu+CI%22) -[![macOS CI](https://github.com/isl-org/Open3D/workflows/macOS%20CI/badge.svg)](https://github.com/isl-org/Open3D/actions?query=workflow%3A%22macOS+CI%22) -[![Windows CI](https://github.com/isl-org/Open3D/workflows/Windows%20CI/badge.svg)](https://github.com/isl-org/Open3D/actions?query=workflow%3A%22Windows+CI%22) +[![Ubuntu CI](https://github.com/isl-org/Open3D/actions/workflows/ubuntu.yml/badge.svg)](https://github.com/isl-org/Open3D/actions?query=workflow%3A%22Ubuntu+CI%22) +[![macOS CI](https://github.com/isl-org/Open3D/actions/workflows/macos.yml/badge.svg)](https://github.com/isl-org/Open3D/actions?query=workflow%3A%22macOS+CI%22) +[![Windows CI](https://github.com/isl-org/Open3D/actions/workflows/windows.yml/badge.svg)](https://github.com/isl-org/Open3D/actions?query=workflow%3A%22Windows+CI%22) **Core features of Open3D include:** From cd4b7f9dfbd17aadeb8bfe19c59213c1c8032d2c Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Wed, 8 Nov 2023 01:04:14 +0100 Subject: [PATCH 05/14] Move to furo and upgrade all dependencies. --- docs/_static/theme_overrides.css | 20 ------------------- .../variant-selector.html} | 0 docs/conf.py | 8 +++----- docs/requirements.txt | 8 ++++---- 4 files changed, 7 insertions(+), 29 deletions(-) delete mode 100644 docs/_static/theme_overrides.css rename docs/_templates/{versions.html => sidebar/variant-selector.html} (100%) diff --git a/docs/_static/theme_overrides.css b/docs/_static/theme_overrides.css deleted file mode 100644 index 250bb7df602..00000000000 --- a/docs/_static/theme_overrides.css +++ /dev/null @@ -1,20 +0,0 @@ -/* Force table wrap: https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html */ -/* override table width restrictions */ -@media screen and (min-width: 767px) { - - .wy-table-responsive table td { - /* !important prevents the common CSS stylesheets from overriding - this as on RTD they are loaded after this stylesheet */ - white-space: normal !important; - } - - .wy-table-responsive { - overflow: visible !important; - } - } - -/* Limit visible text output to about 30 lines and show scrollbar */ -.nboutput .output_area div > pre { - overflow-y: scroll !important; - max-height: 30em; -} diff --git a/docs/_templates/versions.html b/docs/_templates/sidebar/variant-selector.html similarity index 100% rename from docs/_templates/versions.html rename to docs/_templates/sidebar/variant-selector.html diff --git a/docs/conf.py b/docs/conf.py index 079d20bc2f0..fd864cccd5c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -69,7 +69,6 @@ def get_git_short_hash(): "sphinx.ext.todo", "nbsphinx", "m2r2", - "sphinx_rtd_theme", ] if os.environ.get("skip_notebooks", "false") == "true": @@ -132,15 +131,17 @@ def get_git_short_hash(): # The name of the Pygments (syntax highlighting) style to use. pygments_style = "sphinx" +pygments_dark_style = "monokai" # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False + # -- Options for HTML output ---------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = "sphinx_rtd_theme" +html_theme = "furo" html_favicon = "_static/open3d_logo.ico" # Theme options are theme-specific and customize the look and feel of a theme @@ -160,9 +161,6 @@ def get_git_short_hash(): # Display selection of all documentation versions. html_context = {'display_all_docs_versions': True} -# Override theme css -html_css_files = ["theme_overrides.css"] - # added by Jaesik to hide "View page source" html_show_sourcelink = False diff --git a/docs/requirements.txt b/docs/requirements.txt index e8ca97234c5..ab297f6eb30 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,7 +1,7 @@ -docutils==0.17.0 +docutils==0.20.1 +furo==2023.9.10 jinja2==3.1.2 -m2r2==0.3.2 +m2r2==0.3.3.post2 matplotlib==3.7.3 nbsphinx==0.9.3 -sphinx==5.3.0 -sphinx-rtd-theme==1.3.0 +sphinx==7.1.2 \ No newline at end of file From f9480442f77c163b6128e598ae037715aa374780 Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Fri, 10 Nov 2023 20:36:57 +0100 Subject: [PATCH 06/14] Fix display of caption of toctree in furo theme. --- docs/_static/css/furo_overrides.css | 5 +++++ docs/conf.py | 5 ++++- 2 files changed, 9 insertions(+), 1 deletion(-) create mode 100644 docs/_static/css/furo_overrides.css diff --git a/docs/_static/css/furo_overrides.css b/docs/_static/css/furo_overrides.css new file mode 100644 index 00000000000..bc4babc9afe --- /dev/null +++ b/docs/_static/css/furo_overrides.css @@ -0,0 +1,5 @@ +/* In furo, toctree captions needs to be enlarged. */ +.toctree-wrapper.compound .caption { + font-size: 150%; + font-weight: bold; +} \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index fd864cccd5c..23f5ffe796e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -8,7 +8,7 @@ # -*- coding: utf-8 -*- # # Open3D documentation build configuration file, created by -# sphinx-quickstart on Mon Apr 3 14:18:28 2017. +# sphinx-quickstart on Mon Apr 3 14:18:28 2017. # # This file is execfile()d with the current directory set to its # containing dir. @@ -158,6 +158,9 @@ def get_git_short_hash(): # '_static' contains the theme overwrite html_static_path = ["_static"] +# Theme overrides +html_css_files = ['css/furo_overrides.css'] + # Display selection of all documentation versions. html_context = {'display_all_docs_versions': True} From 7b237246e6d340c884769ff1145988a6c216cc9a Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Fri, 10 Nov 2023 20:41:40 +0100 Subject: [PATCH 07/14] Remove only tag, was missing double colon. --- docs/index.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 083cd7e23fa..6be002a714b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,10 +13,6 @@ Open3D: A Modern Library for 3D Data Processing =============================================== -.. only: not latex - - Contents: - .. toctree:: :maxdepth: 1 :caption: Getting Started From c7b9e14dad2f472cc23e502b98b4c6cff12a8d65 Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Fri, 10 Nov 2023 20:45:10 +0100 Subject: [PATCH 08/14] Fix typo. --- docs/jupyter/geometry/distance_queries.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/jupyter/geometry/distance_queries.ipynb b/docs/jupyter/geometry/distance_queries.ipynb index 36038e99e9e..3c7eada9fea 100644 --- a/docs/jupyter/geometry/distance_queries.ipynb +++ b/docs/jupyter/geometry/distance_queries.ipynb @@ -308,7 +308,7 @@ " axis=-1)\n", "intersection_counts = scene.count_intersections(rays).numpy()\n", "# A point is inside if the number of intersections with the scene is even\n", - "# This sssumes that inside and outside is we ll defined for the scene.\n", + "# This assumes that inside and outside are well-defined for the scene.\n", "is_inside = intersection_counts % 2 == 1" ] }, From 298045c1f44852d978985cfa8ee6445ff1ca4201 Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Fri, 10 Nov 2023 21:45:42 +0100 Subject: [PATCH 09/14] Convert admonition from note type to warning, considering many users make these mistakes. --- docs/getting_started.in.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/getting_started.in.rst b/docs/getting_started.in.rst index d3ffdc21956..986cb93f0c8 100644 --- a/docs/getting_started.in.rst +++ b/docs/getting_started.in.rst @@ -35,12 +35,14 @@ Pip (PyPI) pip install open3d # or pip install open3d-cpu # Smaller CPU only wheel on x86_64 Linux (since v0.17+) +.. warning:: -.. note:: Please upgrade your ``pip`` to a version >=20.3 to install Open3D in Linux, e.g. with - ``pip install -U pip>=20.3`` + .. code-block:: bash + + pip install -U pip>=20.3 .. note:: In general, we recommend using a @@ -99,7 +101,7 @@ install the latest development version directly with pip: pip install -U --trusted-host www.open3d.org -f http://www.open3d.org/docs/latest/getting_started.html open3d -.. note:: +.. warning:: The development wheels for Linux are named according to PEP600. Please use ``pip`` version >=20.3 to install them. The wheels are not yet fully PEP600 compliant. @@ -182,7 +184,7 @@ provided here [#]_: only. .. [#] To check the `glibc` version on your system, run :code:`ldd --version`. -.. note:: In Linux, do not link code with different CXX11 ABIs, since this will +.. warning:: In Linux, do not link code with different CXX11 ABIs, since this will most likely cause linker errors or crashes. Most system libraries in recent Linux versions (e.g. if the OS came with GCC versions 5+) use the CXX11 ABI, while PyTorch and Tensorflow libraries typically use the pre CXX11 ABI. From d1ebb72eb3784b671866020cc38045ff8799a222 Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Fri, 10 Nov 2023 21:50:04 +0100 Subject: [PATCH 10/14] Add css overrides and minor html changes to show documentation version selector. --- docs/_static/css/furo_overrides.css | 39 +++++++++++++++++++ docs/_templates/sidebar/variant-selector.html | 25 ++++++------ 2 files changed, 52 insertions(+), 12 deletions(-) diff --git a/docs/_static/css/furo_overrides.css b/docs/_static/css/furo_overrides.css index bc4babc9afe..c3740363329 100644 --- a/docs/_static/css/furo_overrides.css +++ b/docs/_static/css/furo_overrides.css @@ -2,4 +2,43 @@ .toctree-wrapper.compound .caption { font-size: 150%; font-weight: bold; +} + +/* Apply custom CSS for displaying docs version - https://github.com/pradyunsg/furo/pull/500 */ +#furo-versions { + font-size: var(--sidebar-item-font-size); +} + +#furo-versions .caption { + display: inline-block; + color: var(--color-sidebar-caption-text); + font-weight: bold; + text-transform: uppercase; + font-size: var(--sidebar-caption-font-size); + padding-right: var(--sidebar-expander-width); + margin-top: 0; +} + +#furo-versions input[type=checkbox] { + display: none; + position: absolute; + box-sizing: border-box; + padding: 0; + overflow: visible; +} + +#furo-versions input[type=checkbox]:checked ~ .rst-other-versions { + display: inline-block; + line-height: var(--sidebar-item-line-height); + padding: var(--sidebar-item-spacing-vertical) var(--sidebar-item-spacing-horizontal); + text-decoration: none; +} + +#furo-versions .rst-other-versions { + display: none; +} + +#furo-versions .versions-label { + position: relative; + float: right; } \ No newline at end of file diff --git a/docs/_templates/sidebar/variant-selector.html b/docs/_templates/sidebar/variant-selector.html index b660cd44101..cb7a7e9c727 100644 --- a/docs/_templates/sidebar/variant-selector.html +++ b/docs/_templates/sidebar/variant-selector.html @@ -1,20 +1,21 @@ {% if display_all_docs_versions %} {# Add rst-badge after rst-versions for small badge style. #} -
- - Docs version - {{ version }} - - + {% endif %} \ No newline at end of file From ed4de40ec6a17f39841b26b4a91f931db29314f0 Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Fri, 10 Nov 2023 21:56:48 +0100 Subject: [PATCH 11/14] Center align open3d-ml image. --- docs/open3d_ml.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/open3d_ml.rst b/docs/open3d_ml.rst index a4afdcd0e5f..c8a8a5d68ba 100644 --- a/docs/open3d_ml.rst +++ b/docs/open3d_ml.rst @@ -5,6 +5,7 @@ Open3D-ML .. image:: https://raw.githubusercontent.com/isl-org/Open3D-ML/master/docs/images/getting_started_ml_visualizer.gif :width: 480px + :align: center Open3D-ML is an extension of Open3D for 3D machine learning tasks. It builds on top of the Open3D core library and extends it with machine learning tools for From c6fc5e13d23006563fa19509bfd5d2d7418e15d2 Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Fri, 10 Nov 2023 22:10:23 +0100 Subject: [PATCH 12/14] Fix code style and update CHANGELOG.md --- CHANGELOG.md | 1 + docs/conf.py | 1 - 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0d3ba84ed84..c28c4d86739 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,6 +21,7 @@ * Fix printing of tensor in gpu and add validation check for bounds of axis-aligned bounding box (PR #6444) * Python 3.11 support. bump pybind11 v2.6.2 -> v2.11.1 * Check for support of CUDA Memory Pools at runtime (#4679) +* Migrate Open3d documentation to furo theme ✨ (#6470) ## 0.13 diff --git a/docs/conf.py b/docs/conf.py index 23f5ffe796e..d542d032ac1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -136,7 +136,6 @@ def get_git_short_hash(): # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False - # -- Options for HTML output ---------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for From ad34fdbdc9a1e3ce6870a11c65df4e84fbbe95f6 Mon Sep 17 00:00:00 2001 From: Saurabh Khanduja Date: Mon, 13 Nov 2023 03:00:56 +0100 Subject: [PATCH 13/14] todo_include_todos was given twice in conf.py, remove earlier entry. --- docs/conf.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index d542d032ac1..a02dfcf53e5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -133,9 +133,6 @@ def get_git_short_hash(): pygments_style = "sphinx" pygments_dark_style = "monokai" -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = False - # -- Options for HTML output ---------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for From 6be9fed6f479f01cd8f56d64c1d56929be711cfd Mon Sep 17 00:00:00 2001 From: Sameer Sheorey Date: Tue, 14 Nov 2023 13:16:38 -0800 Subject: [PATCH 14/14] Fix for references rendering. --- docs/_static/css/furo_overrides.css | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/_static/css/furo_overrides.css b/docs/_static/css/furo_overrides.css index c3740363329..4743eee253c 100644 --- a/docs/_static/css/furo_overrides.css +++ b/docs/_static/css/furo_overrides.css @@ -41,4 +41,9 @@ #furo-versions .versions-label { position: relative; float: right; -} \ No newline at end of file +} + +/* Fix for references. See Open3D PR #6470 */ +div.citation > span { + padding-right: 2rem; +}