Google Season of Docs at Open3D
Project: Improvements to the Python & C++ API
Primary Mentor: Yixing Lao
Technical Writer: Rohan Rathi
Work Product:
Brief
Open3D is a an emerging open source organisation under the OSVF that aims to provide a library for 3D processing such as scene reconstruction from images, visualization and much more. The codebase is entirely in C++ with an API exposed in Python through python bindings. My aim in the project was to add technical documentation of the work done in C++ by adding the relevant docstrings to the classes, functions and data specified in the file (which would be built by doxygen to generate the function & class level documentation) and bring it upto speed with the Python API. Along with this I corrected and proofread the documentation in the Python API to increase cross doc consistency and added more documentation wherever I felt was necessary.
Project Report
Open3D uses Doxygen to generate the C++ documentation and Sphinx to generate the Python documentation. The documentation is written in restructured text. Open3D is extensively used in Python which leads to the Python documentation being pretty much up to date.
A lot of the algorithms in Open3D are implementations of research papers. Usage requires an expertise in the area of 3D Graphics. This also makes necessary to add links to relevant papers to clarify the approach followed.
The first contribution I made was to add documentation to build docs. An essential step to make future contributions to documentation possible. I also added documentation for PinholeCameraIntrinsic to show that I can build the source code and know how to work with Doxygen & Sphinx.
Plan
Then I planned on how to break the documentation in C++ & Python into workable chunks. I planned on mapping the current C++ docs to bring it upto speed to Python and add any missing details as I worked on writing the documentation. Then I planned on bringing the Python docs upto speed with C++ with any additional changes I made in the previous step. Lastly, I reviewed the Python & C++ docs to check for inconsistencies, refine the docs and elaborate wherever I felt necessary.
Coding
I iteratively added documentation for the C++ docs corresponding to entities in Python docs (Eg colormap, camera, bounding box). I added docs for the base classes separately which derive the rest of the classes in C++. Thus, I added documentation for Image & Geometry, Geometry2D & Geometry3D. I finished work on the C++ docs and raised a Pull Request that contained all of the remaining documentation in C++.
I later referenced this PR while validating the Python documentation and changes wherever I felt necessary in Python. I raised an initial set of PR’s for Python then amended the remaining Python documentation in the main pull request
Future Work
The main pull request is currently under review I am working with the developer team to complete review and merge the pull request as fast as possible. I feel that with review there will be inconsistencies in the docs, so I plan on reviewing the docs a few more times. I also feel there are areas lacking in the documentation where gaps can be filled to help novices grasp the concepts of 3D Graphics. After the technical writeup is complete I plan on taking an objective view of the challenges faced by a new comer to this field.
Learnings
I learnt the usage of Doxygen & Sphinx and how they build documentation. Improved my understanding of Pybind to generate a Python API for code written in C++. I also feel I improved my own understanding of 3D Graphics by far.