Review and simplify API documentation generation

[niketagrawal]

Challenges and issues in current implementation

• The process of creating new API documentation is cumbersome. It involves multiple repositories. It is desired to have this process simplified.

• Process of adding a new feature currently:

  • Add C++ code changes in tudat
  • Add python bindings in tudatpy
  • Add API documentation for the bindings in tudat-multidoc repo

• A separate repository tudat-multidoc is used to generate the API documentation for the bindings. It uses a custom yml format to specify the docstrings and a separate docstrings.h file to generate the docstrings in NumPy doc style.

• Currently, the docstrings in the native python code in tudatpy repository are not rendered in html format on the tudat docs website. Only the API docs are rendered. It is desired to have both docs rendered as html on the public facing documentation.

• The Azure pipelines build and test the source code for 12 combinations (3 operating systems and 4 python versions each). Currently, the API docs are updated on the website if one of these passes (Linux Python 3.8?). It is desired to have the API docs updated only when the build and test pass for all platforms and python versions.

Work plan

• Gather requirements for writing, building, and hosting the API documentation #147

• Explore options to simplify writing binding docstrings and generating API documentation without relying on tudat-multidoc

• (Optional) Continuous Integration for API documentation

Explore options to simplify writing binding docstrings and generating API documentation without relying on tudat-multidoc: Ideas to try as proof of concepts

• [PoC] API docs refactoring: Include the docstring in the binding code itself replacing the call to the function get_docstring(). #149

• [PoC] API docs refactoring: Use one time generated docstrings.h as the primary source for adding and extracting the docstrings #150

• API docs refactoring proof of concept: Break down the above docstrings.h into several small files containing docstrings of specific modules and place them in their respective directories. This will be a modular version of the second approach.