Upgrade documentation techstack (#6470)

* Move conf.in.py to conf.py. * Upgrade all docs dependencies and replace open3d_sphinx_theme with sphinx_rtd_theme * Lower docutils to version 0.17.0 and sort dependencies * Fix CI badges. * Move to furo and upgrade all dependencies. * Fix display of caption of toctree in furo theme. * Add css overrides and minor html changes to show documentation version selector. * todo_include_todos was given twice in conf.py, remove earlier entry. * Fix for references rendering. --------- Co-authored-by: Sameer Sheorey <sameer.sheorey@intel.com>
isl-org · Nov 14, 2023 · 2a11e0e · 2a11e0e
1 parent 392fcb9
commit 2a11e0e
Show file tree

Hide file tree

Showing 12 changed files with 101 additions and 79 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -18,10 +18,11 @@
 * Changed TriangleMesh to store materials in a list so they can be accessed by the material index (PR #5938)
 * Support multi-threading in the RayCastingScene function to commit scene (PR #6051).
 * Fix some bad triangle generation in TriangleMesh::SimplifyQuadricDecimation
-* Fix printing of tensor in gpu and add validation check for bounds of axis-aligned bounding box (PR #6444)  
+* 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)
 * Fix `toString`, `CreateFromPoints` methods and improve docs in `AxisAlignedBoundingBox`. 🐛📝
+* Migrate Open3d documentation to furo theme ✨ (#6470)
 
 ## 0.13
 

diff --git 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:**
 

diff --git 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/_static/css/furo_overrides.css b/docs/_static/css/furo_overrides.css
@@ -0,0 +1,49 @@
+/* In furo, toctree captions needs to be enlarged. */
+.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;
+}
+
+/* Fix for references. See Open3D PR #6470 */
+div.citation > span {
+	padding-right: 2rem;
+}
diff --git a/docs/_static/theme_overrides.css b/docs/_static/theme_overrides.css
diff --git a/docs/_templates/sidebar/variant-selector.html b/docs/_templates/sidebar/variant-selector.html
@@ -0,0 +1,21 @@
+{% if display_all_docs_versions %}
+{# Add rst-badge after rst-versions for small badge style. #}
+  <div id="furo-versions" class="rst-versions sidebar-tree" role="note" aria-label="versions" tabindex="0">
+      <p class="caption">Docs Version</p>
+      <input type="checkbox" id="checkbox_toggle" class="toctree-checkbox versions-checkbox" role="switch">
+      <label id="versions-label" class="versions-label" for="checkbox_toggle">
+          <div class="visually-hidden">Toggle child pages in navigation</div>
+          <i class="icon">
+            <svg>
+              <use href="#svg-arrow-right"></use>
+            </svg>
+          </i>
+      </label>
+
+    <!-- A hack to include an external page to get around CORS policy -->
+    <!-- https://stackoverflow.com/a/15250208/1255535 -->
+    <div class="rst-other-versions">
+        <script src="http://www.open3d.org/docs/versions.js"></script>
+    </div>
+  </div>
+{% endif %}
diff --git a/docs/conf.in.py → docs/conf.py b/docs/conf.in.py → 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.
@@ -68,7 +68,7 @@ def get_git_short_hash():
     "sphinx.ext.napoleon",
     "sphinx.ext.todo",
     "nbsphinx",
-    'm2r2',
+    "m2r2",
 ]
 
 if os.environ.get("skip_notebooks", "false") == "true":
@@ -131,25 +131,18 @@ def get_git_short_hash():
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = "sphinx"
-
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = False
+pygments_dark_style = "monokai"
 
 # -- 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 = 'alabaster'
-theme_path = "@OPEN3D_SPHINX_THEME_SOURCE_DIR@"
-html_theme = "sphinx_rtd_theme"
-html_theme_path = [theme_path]
+html_theme = "furo"
 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 +152,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"]
+
+# Theme overrides
+html_css_files = ['css/furo_overrides.css']
+
+# Display selection of all documentation versions.
+html_context = {'display_all_docs_versions': True}
 
 # added by Jaesik to hide "View page source"
 html_show_sourcelink = False

diff --git 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.

diff --git 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

diff --git 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"
    ]
   },

diff --git 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

diff --git 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
+docutils==0.20.1
+furo==2023.9.10
+jinja2==3.1.2
+m2r2==0.3.3.post2
+matplotlib==3.7.3
+nbsphinx==0.9.3
+sphinx==7.1.2