improve documentation

LiangliangNan · Jan 19, 2025 · 0c52b28 · 0c52b28
1 parent d67fa44
commit 0c52b28
Show file tree

Hide file tree

Showing 7 changed files with 54 additions and 53 deletions.
diff --git a/easy3d/util/version.h b/easy3d/util/version.h
@@ -59,7 +59,7 @@ namespace easy3d {
 #define EASY3D_VERSION_NR 1020601
 
 /// Easy3D release date, in the format YYYYMMDD.
-#define EASY3D_RELEASE_DATE 20250118
+#define EASY3D_RELEASE_DATE 20250119
 
 
 #endif  // EASY3D_UTIL_VERSION_H
diff --git a/python/README.md b/python/README.md
@@ -1,16 +1,13 @@
-# Easy3D Python Bindings
+### Obtain/Build Easy3D Python bindings
 
-Python bindings for the Easy3D library.
+Prebuilt Python bindings are available from the [Releases](https://github.com/LiangliangNan/Easy3D/releases) page. 
+Download the wheel file for your platform and Python version, and install it using `pip`.
 
-More information about Easy3D:
-https://github.com/LiangliangNan/Easy3D
-
-### Build Easy3D bindings
-
-Make sure you have [Python](https://www.python.org/downloads/) installed.
-Then switch on the CMake option `Easy3D_BUILD_PYTHON_BINDINGS`, run CMake, and then build. After building Easy3D, you
-can find the Python bindings module `PyEasy3D` (`PyEasy3D.pyd` on Windows, `PyEasy3D.so` on macOS/Linux) in
-`YOUR_BUILD_DIRECTORY/lib/python/easy3d`.
+If the prebuilt bindings are not available for your platform or specific version of Python, you can build it from the 
+source code. Make sure you have [Python](https://www.python.org/downloads/) installed.
+Then switch on the CMake option `Easy3D_BUILD_PYTHON_BINDINGS`, run CMake, and then build Easy3D. 
+After building Easy3D, you can find the Python bindings module `PyEasy3D` (`PyEasy3D.pyd` on Windows, `PyEasy3D.so` 
+on macOS/Linux) in `YOUR_BUILD_DIRECTORY/lib/python/easy3d`.
 
 ### Use Easy3D bindings in Python code
 
@@ -31,7 +28,8 @@ viewer.run()
 
 **Note**: the Python version used for running the code should match the version used for building the bindings.
 
-### (Optional) Installation
+
+### Installation (Optional)
 
 If you want to avoid specifying the path of the generated bindings in your Python code, you can create a wheel (`.whl`) 
 file for the bindings and install it globally. This will make Easy3D work like other Python packages such as [Numpy](https://numpy.org/).
@@ -54,15 +52,4 @@ Below are the detailed steps for creating the wheel file and installation.
 
   You can verify the installation by running the following command:
 
-  - `pip show easy3d`
-
-
-
-### System Dependencies (typically already installed for almost all users)
-Before installing `easy3d`, ensure that the following system libraries are installed:
-
-- **OpenGL**: Required for rendering.
-  - On **Ubuntu/Debian**: `sudo apt install libgl1-mesa-dev`
-  - On **Windows**: Install the latest graphics drivers from your GPU manufacturer. 
-  - On **macOS**: Pre-installed.
-  - On **Fedora**: `sudo dnf install mesa-libGL-devel`
+  - `pip show easy3d`
diff --git a/python/docs/source/_templates/breadcrumbs.html b/python/docs/source/_templates/breadcrumbs.html
@@ -0,0 +1,3 @@
+{% extends "!breadcrumbs.html" %}
+{% block breadcrumbs_aside %}
+{% endblock %}
diff --git a/python/docs/source/_templates/footer.html b/python/docs/source/_templates/footer.html
@@ -0,0 +1,3 @@
+<div class="footer">
+    Last updated on {{ last_updated }}.
+</div>
diff --git a/python/docs/source/conf.py b/python/docs/source/conf.py
@@ -21,7 +21,7 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'Easy3D Python Tutorials'
+project = 'Easy3D Python Bindings'
 copyright = '2025, Liangliang Nan'
 author = 'Liangliang Nan'
 release = '2.6.1'
@@ -40,6 +40,7 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
     "sphinx_gallery.gen_gallery",
+    'myst_parser',  # Markdown support
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -50,14 +51,19 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
-
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 # html_theme = 'alabaster'          # Or your preferred theme
 # html_theme = 'classic'
 html_theme = 'sphinx_rtd_theme'
 
+# Last updated format
+html_last_updated_fmt = '%Y-%m-%d %H:%M:%S'
+
+# Path to templates
+templates_path = ['_templates']
+
 # Sphinx-Gallery configuration
 sphinx_gallery_conf = {
     "examples_dirs": ["../../tutorials"],       # Path to the tutorials directory
@@ -68,14 +74,6 @@
     "write_computation_times": False,           # Don't write computation times
 }
 
-# Autodoc settings (optional)
-autodoc_default_options = {
-    "members": True,
-    "undoc-members": True,
-    "private-members": False,
-    "show-inheritance": True,
-}
-
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".

diff --git a/python/docs/source/index.rst b/python/docs/source/index.rst
@@ -3,33 +3,38 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Easy3D Python Tutorials
-=====================================
+Easy3D Python Bindings
+======================
+
+About
+-----
+
+`Easy3D <https://github.com/LiangliangNan/Easy3D>`_ is implemented in C++ and comes with Python bindings.
+This documentation provides documentation for the Python bindings of Easy3D.
+
+.. include:: ../../README.md
+   :parser: myst_parser.sphinx_
+
+
+Related Links
+~~~~~~~~~~~~~
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
-
-   generated_tutorials/index
 
-About
------
+   Easy3D Python Bindings <./index.html>
 
-This documentation provides tutorials for learning the Python bindings of Easy3D, covering various examples in the `tutorials` directory.
-More tutorials will be added in the future.
+   generated_tutorials/index
 
-If you are interested in the original C++ APIs, please check out here: https://github.com/LiangliangNan/Easy3D.
+   Code for Python Tutorials <https://github.com/LiangliangNan/Easy3D/tree/main/python/tutorials>
 
-**Sections include**:
+   Easy3D Documentation <https://3d.bk.tudelft.nl/liangliang/software/easy3d_doc/html/index.html>
 
-- Step-by-step Python examples with code and comments.
-- Auto-generated HTML tutorials for each `.py` file in the `tutorials` directory.
+   Easy3D Pre-built Binaries <https://github.com/LiangliangNan/Easy3D/releases>
 
-Further Reading
----------------
+   Easy3D Source Code <https://github.com/LiangliangNan/Easy3D>
 
-- Official Python documentation: https://docs.python.org/
-- Sphinx documentation: https://www.sphinx-doc.org/
+   Code for C++ Tutorials <https://github.com/LiangliangNan/Easy3D/tree/main/tutorials>
 
 .. Indices and tables
 .. ==================

diff --git a/python/tutorials/GALLERY_HEADER.txt b/python/tutorials/GALLERY_HEADER.txt
@@ -2,5 +2,10 @@
 Easy3D Python Tutorials
 ===========================
 
-Welcome to the Easy3D Python Tutorials gallery! Here you will find tutorials to help you understand and work with the Easy3D library.
+Welcome to the Easy3D Python tutorials!
+
+The tutorials (with code) cover various examples showcasing the most useful functions provided by
+`Easy3D <https://github.com/LiangliangNan/Easy3D>`_, as well as explaining the relevant concepts behind
+the functions.  Easy3D and its tutorials are still under active development. If you would like to contribute,
+please check `here <https://github.com/LiangliangNan/Easy3D/blob/main/CONTRIBUTING.md>`_.