Improve documentation #6307

saurabheights · 2023-08-12T15:52:45Z

Type

Bug fix (non-breaking change which fixes an issue): Fixes build warnings, missing docs, mostly cleanup.
New feature (non-breaking change which adds functionality). Resolves #
Breaking change (fix or feature that would cause existing functionality to not work as expected) - The items order in documentation layout changes slightly. I will comment wherever these changes are made today. #

Motivation and Context

Reviewing documentation and required cleanup. This PR only address some of the issues. Each issue is fixed in single commit, so should be easier to review commit-wise. More changes will follow along in a separate PR.

P.S. My end goal is to later on address issues like architecture documentation request, fix existing documentation issues as one fixed earlier here, etc.

Checklist:

I have run python util/check_style.py --apply to apply Open3D code style
to my code.
This PR changes Open3D behavior or adds new functionality.
- Both C++ (Doxygen) and Python (Sphinx / Google style) documentation is
  updated accordingly.
- I have added or updated C++ and / or Python unit tests OR included test
  results (e.g. screenshots or numbers) here.
I will follow up and update the code if CI fails.
For fork PRs, I have selected Allow edits from maintainers.

Description

I will add screenshot commit wise wherever necessary.

This change is

…ckage.

…on together.

…nings.

…in any toctree`.

review-notebook-app · 2023-08-12T15:52:50Z

Check out this pull request on

See visual diffs & provide feedback on Jupyter Notebooks.

Powered by ReviewNB

docs/getting_started.in.rst

saurabheights · 2023-08-12T15:56:23Z

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


Removed missing shell script, as well as why Opencv is used (most users dont care about that) and also its easy to make this doc redundant when adding a new example where opencv is used (which might have already happened, I do need to check if numpy, matplotlib, opencv-python are the only needed libs. Maybe adding etc. and some requirements_example.txt file would be better.

saurabheights · 2023-08-12T16:00:25Z

docs/index.rst

    docker
+    arm
+    open3d_ml


I moved open3d_ml to the bottom and arm above, with docker option closer to right after compilation, since new user would want to see how to get started with open3d faster. Let me know if this is alright or not.

saurabheights · 2023-08-12T16:05:48Z

docs/index.rst

@@ -88,3 +71,20 @@ Open3D: A Modern Library for 3D Data Processing
    python_example/pipelines/index
    python_example/utility/index
    python_example/visualization/index
+


As previous commit, this one focuses on putting all python related stuff together, i.e. Tutorials, Python API and Python Examples. C++ API after Python and Contribution in the end.

docs/tutorial/geometry/index.rst

saurabheights · 2023-08-12T16:56:12Z

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"


More info on why here - spatialaudio/nbsphinx#373 (comment)

P.S. Just noticed that the changes here are getting over written somehow when building docs. Will check and fix this commit.

Found my oversight. So, changes here are getting ignored because a pre-built t_icp_registration notebook file is getting downloaded in make_docs.py due to #4321.

Is the documentation still built without cuda on CI/CD?

I think so. It is safe to keep the changes here now, we can study the best option regarding large notebook files in another PR.

…d-string.` This escapes vertical bars in bash tree output in pydocs but doesnt fix rendering in html.

saurabheights · 2023-08-12T17:09:36Z

docs/conf.in.py

 def setup(app):
    app.connect("autodoc-skip-member", skip)
+    app.connect("autodoc-process-docstring", escape_vertical_bars)


The issue comes from vertical bars in python docs which are from tree command - http://open3d.org/docs/release/python_api/open3d.data.RedwoodIndoorLivingRoom1.html. This change fixes the warning but the output is in html paragraph tag and new lines get ignored.

There was an alternate option to also remove output of tree command from docs, but I thought better keep tree output. Python docs are nicer, even if sphinx is not yet. Any ideas on how to fix for sphinx as well?

Hi @saurabheights this issue actually originates from C++ code where the doc string is written, so the best way to fix this is there. We should not need a python postprocessing script here. The doscstring is rst and the rst syntax for literal text is:

https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#literal-blocks

(double colon and indented block)

Can you switch the pybind docstring to this syntax and see if that fixes this issue?

The pybind docstring is here:

https://github.com/isl-org/Open3D/blob/master/cpp/pybind/data/dataset.cpp#L979

Similarly, the C++ doxygen documentation is also mis-formatted:

http://www.open3d.org/docs/latest/cpp_api/classopen3d_1_1data_1_1_redwood_indoor_living_room1.html#details

Doxygen uses markdown syntax for code blocks:
https://www.doxygen.nl/manual/markdown.html#mddox_code_blocks

Here is the C++ documentation:

https://github.com/isl-org/Open3D/blob/master/cpp/open3d/data/Dataset.h#L726

@ssheorey Thanks for catching this. Learnt something new. Reverted my earlier postprocessing script and added suggested solution. Worked nicely for both sphinx and doxygen.

theNded

Thanks for the kind contribution!

LGTM with minor change requests. I will also have to study how to render the tree structure correctly and will post my feedback later.

docs/conf.in.py

docs/tutorial/geometry/index.rst

docs/make_docs.py

theNded · 2023-08-13T18:22:19Z

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"


I think so. It is safe to keep the changes here now, we can study the best option regarding large notebook files in another PR.

ssheorey · 2023-08-14T17:58:38Z

docs/conf.in.py

 def setup(app):
    app.connect("autodoc-skip-member", skip)
+    app.connect("autodoc-process-docstring", escape_vertical_bars)


Hi @saurabheights this issue actually originates from C++ code where the doc string is written, so the best way to fix this is there. We should not need a python postprocessing script here. The doscstring is rst and the rst syntax for literal text is:

https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#literal-blocks

(double colon and indented block)

Can you switch the pybind docstring to this syntax and see if that fixes this issue?

The pybind docstring is here:

https://github.com/isl-org/Open3D/blob/master/cpp/pybind/data/dataset.cpp#L979

Similarly, the C++ doxygen documentation is also mis-formatted:

http://www.open3d.org/docs/latest/cpp_api/classopen3d_1_1data_1_1_redwood_indoor_living_room1.html#details

Doxygen uses markdown syntax for code blocks:
https://www.doxygen.nl/manual/markdown.html#mddox_code_blocks

Here is the C++ documentation:

https://github.com/isl-org/Open3D/blob/master/cpp/open3d/data/Dataset.h#L726

ssheorey

Thanks @saurabheights ! This looks good!

saurabheights added 13 commits August 10, 2023 21:13

Add install with upgrade option when installing latest development pa…

2e8ee6d

…ckage.

util/install-deps-python.sh was removed in isl-org#2146

86e7a2f

Grammar fix.

3ea347d

Move open3d_ml and arm to after docker.

381882d

organize TOC - Move C++ and Contribution to end and keep python secti…

17a27a3

…on together.

Fix sphinx warnings (Title underline too short).

0b8edfd

Fix extra heading drop when going one level down.

201b6bd

Fix cross reference links

5d798fd

Add files/directories to ignore for sphinx, reduces inconsistency war…

42a1106

…nings.

Fix Unknown directive type "code_block" warning.

4c48feb

Add uvmaps to official docs, fix - `WARNING: document isn't included …

9af3bdc

…in any toctree`.

Fix yaml lexer name - See https://pygments.org/languages/

d71cd20

Correct the extension

9c956d2

saurabheights commented Aug 12, 2023

View reviewed changes

docs/getting_started.in.rst Show resolved Hide resolved

saurabheights commented Aug 12, 2023

View reviewed changes

docs/tutorial/geometry/index.rst Show resolved Hide resolved

saurabheights commented Aug 12, 2023

View reviewed changes

Fix warnings - `Inline substitution_reference start-string without en…

fb7c71c

…d-string.` This escapes vertical bars in bash tree output in pydocs but doesnt fix rendering in html.

saurabheights force-pushed the khanduja/fix_docs_1 branch from 544ee3e to fb7c71c Compare August 12, 2023 17:09

saurabheights commented Aug 12, 2023

View reviewed changes

saurabheights added 2 commits August 13, 2023 03:18

Minor code refactoring of make_docs.py

c99fd1b

Only copy open3d_tutorial.py once

af3ba12

theNded self-requested a review August 13, 2023 18:06

theNded approved these changes Aug 13, 2023

View reviewed changes

Move list of classes to a global variable

04d8799

ssheorey requested changes Aug 14, 2023

View reviewed changes

Use f-strings as requested in PR

3d82438

saurabheights added 5 commits August 15, 2023 13:32

Add python_api_in as ignored directory.

549c739

Revert all changes made for correcting vertical bar in pydocs

0d675cd

Fix pybind docs with literal block for tree output

a3cbf05

Fix doxygen docs with code block for tree output

e807806

Correct class names in doxygen docs for RedWood dataset

cfd570f

saurabheights requested a review from ssheorey August 15, 2023 21:10

ssheorey approved these changes Aug 17, 2023

View reviewed changes

ssheorey merged commit c7718fd into isl-org:master Aug 17, 2023
36 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve documentation #6307

Improve documentation #6307

saurabheights commented Aug 12, 2023 •

edited

review-notebook-app bot commented Aug 12, 2023

saurabheights Aug 12, 2023 •

edited

saurabheights Aug 12, 2023 •

edited

saurabheights Aug 12, 2023

saurabheights Aug 12, 2023 •

edited

saurabheights Aug 12, 2023

theNded Aug 13, 2023

saurabheights Aug 12, 2023 •

edited

ssheorey Aug 14, 2023

saurabheights Aug 15, 2023

theNded left a comment

theNded Aug 13, 2023

ssheorey Aug 14, 2023

ssheorey left a comment

Improve documentation #6307

Improve documentation #6307

Conversation

saurabheights commented Aug 12, 2023 • edited

Type

Motivation and Context

Checklist:

Description

review-notebook-app bot commented Aug 12, 2023

saurabheights Aug 12, 2023 • edited

Choose a reason for hiding this comment

saurabheights Aug 12, 2023 • edited

Choose a reason for hiding this comment

saurabheights Aug 12, 2023

Choose a reason for hiding this comment

saurabheights Aug 12, 2023 • edited

Choose a reason for hiding this comment

saurabheights Aug 12, 2023

Choose a reason for hiding this comment

theNded Aug 13, 2023

Choose a reason for hiding this comment

saurabheights Aug 12, 2023 • edited

Choose a reason for hiding this comment

ssheorey Aug 14, 2023

Choose a reason for hiding this comment

saurabheights Aug 15, 2023

Choose a reason for hiding this comment

theNded left a comment

Choose a reason for hiding this comment

theNded Aug 13, 2023

Choose a reason for hiding this comment

ssheorey Aug 14, 2023

Choose a reason for hiding this comment

ssheorey left a comment

Choose a reason for hiding this comment

saurabheights commented Aug 12, 2023 •

edited

saurabheights Aug 12, 2023 •

edited

saurabheights Aug 12, 2023 •

edited

saurabheights Aug 12, 2023 •

edited

saurabheights Aug 12, 2023 •

edited