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

[niketagrawal]

Proof of concept implementation steps

Make the below changes in a feature branch in tudatpy repository. Then, use tudat-bundle to fetch these changes within the tudatpy git submodule and build tudat and tudatpy locally.

• Generate docstrings.h containing the docstrings for all the bindings present in tudatpy repository. To generate the docstrings, use tudat-bundle and build API docs in tudat-multidoc git submodule. Refer tudat-bundle readme for the steps. tudat-multidoc also generates scalartypes.h alongside. We need this file as well.
• Put the generated docstrings.h in tudatpy/tudatpy/kernel/
• Delete the existing dosctrings.h and scalartypes.h in tudatpy/include/tudatpy/
• Specify the path to the new docstrings.h and scalartypes.h in tudatpy CMakeLists.txt file. TO do this, modify the CMakeLists.txt of tudatpy to include the directory tudatpy/tudatpy/kernel/, and replace the include path of these files in all bindings code files.
• .rst files are needed in tudatpy/docs/source for each module containing reference to functions and methods from which the docstrings are to be extracted, so sphinx can extract the docs from these files. Generate these files following the steps in tudat-multidoc README. These .rst files can be generated ones and used thereafter by committing them to tudatpy repository.
• Specify path of the python extension modules in tudatpy/docs/source/conf.py: sys.path.insert(0, os.path.abspath('../../build/tudatpy')) in the else loop
• Modify the build logic in tudat-bundle to bypass the usage of tudat-multidoc for generation of docstrings.h file. We want to use the docstring.h file that we generated in the first step. Replace the include path of the docstrings.h file to tudatpy/tudatpy/kernel/
• Run the build.sh script to build tudat and tudatpy
• Build the docs by running make html inside tudatpy/docs/. This step should generate html files in the _build folder.

Development cycle this PoC will lead to

• Clone tudat-bundle
• Add cpp code changes in tudat git submodule on a new feature branch.
• Add bindings in tudatpy git submodule on a new feature branch.
• Add binding docstrings in docstrings.h in tudatpy git submodule
• Add a reference for the new function in the respective .rst file in tudatpy/docs/source
• Build tudat and tudaty using build.sh
• Run make html from inside the tudatpy git submodule and test the html files generated locally
• Push tudapty and tudat feature branches to the respective repositories and open a pull request for each.

Potential issues with this approach [Resolved]

• Sphinx can extract docstrings from the compiled Python extension modules provided the docstrings are embedded in binding code itself and the target python extension module is discoverable by the interpreter, i.e., there is a src/tudatpy/init.py, or python/tudatpy/init.py at the root of the repository as shown in this example https://github.com/pybind/scikit_build_example. This is not the case in tudatpy. It is not yet known if Sphinx can fetch doctrings from a header file and map them to the corresponding extension module.

[niketagrawal]

• Changes are in pull request Feature/150 docstrings #157
• Pull request Feature/150 docstrings #157 will be followed by a pull request to make changes to docs/src/conf.py that uses tudatpy dev conda package instead of multidoc to build docs on Read the Docs.

[niketagrawal]

Closing this pull request as changes are merged via #157 .

Pull request #175 contains the follow-up changes. Dependency on using multidoc to build the docs on read the docs will be removed by this PR.