[BUG] Include Python native docs on the API docs page

[niketagrawal]

Documentation (docstrings) from the pure Python modules in the tudatpy repository should appear on the API docs page alongside the API docs for the bindings.

• Determine the code block responsible for including the python native docs to the API docs page
• Make changes to include the python native docs
• build and test rendering of python native docs locally
• Render bindings and python native docs together

[niketagrawal]

Implementation in WIP/extract-docs-from-python-modules

• Python modules from which docstrings are to be extracted as documentation must be mentioned in index.rst either directly or by referencing to another file where the specific modules are listed. The example implementation in the above feature branch extracts docstrings from two pure Python modules in tudatpy repository. See index.rst and the api_reference_python.rst
• To generate Python native docs rendered in html locally, check out the branch, build the docs using make html and view the html in the browser.
• Sphinx needs the python modules to be importable. This means that docs can't be generated from modules like expose_kernel_module.py unless they are moved inside the tudatpy/ in the root of the repository.
• Which python modules should be included in the list of the modules from which documentation will be generated by extracting the docstrings?
• Some python modules such as elements.py and horizons_ephemeris.py have incorrect imports which result in docs build failure. For the proof of concept, these imports are commented out in the code. CI for the tudatpy repository will aid in fail-safe introduction of these code changes.
• When the docs are built locally, the body of the if block in conf.py is not hit. The body of the else specifies the path to the source files for which the docstrings are extracted. This way the Python native docs are rendered on the API docs page.
• The binding docs and the Python native docs could not be rendered together in html locally so far. When the body of the if loop is modified to be executed locally, links to the functions appear in the rendered docs, but they are empty. This is because when the docs are built, index.rst is overwritten by the logic inside the body of the if loop.

[niketagrawal]

Work on this issue will be resumed after #146

[niketagrawal]

Python native modules which need to rendered together with the API docs

• https://github.com/tudat-team/tudatpy/tree/develop/tudatpy/numerical_simulation/environment_setup/gravity_field
• https://github.com/tudat-team/tudatpy/tree/develop/tudatpy/numerical_simulation/environment_setup/ephemeris

[niketagrawal]

Proof of concept for rendering the docstrings for Python native code (for the two modules listed above) alongside that of the bindings

• Check out the branch PoC/render-python-native-api-docs-together
• Create a conda environment using the file docs/environment_readthedocs.yaml. use the command conda env create -f docs/environment_readthedocs.yaml
• Activate the conda environment
• Change directory to the docs folder cd docs/
• Build the docs by executing make html
• html pages are generated in the docs/build/html directory. Open the page index.html in the browser.
• Navigate to numerical_simulation > environment_setup > gravity_field. You should see the function central_sbdb from the python native module sbdb_wrapper.py there.
• Navigate to numerical_simulation > environment_setup > ephemeris. You should see the function jpl_horizons from the python native module horizons_wrapper.py there.

Test status on Read the Docs

Changes work fine on read the docs. See the rendered docs for this proof of concept: https://py.api.tudat.space/en/poc-render-python-native-api-docs-together/

Points to address going forward

• tudatpy (v0.8.0dev7) is not compatible with the latest dev version of tudat (v2.13.0.dev11). The docs could be built only when tudat was downgraded to v2.13.0.dev10 as is the case in the develop branch of tudatpy.
• Do the docstrings in the python modules tudatpy/elements.py and tudaty/horizins_ephemeris need to be rendered on the API docs website? Do they correspond to any particular C++ module like the two listed previously?

To do

• Modify the conf.py to allow building docs from source: Add path to tudatpy shared library. Separate build logic of local and read the docs using if loop
• Remove commented code from conf.py

[niketagrawal]

Pull request will be created after #157 is merged

[niketagrawal]

Pull request #166 is created to fix this issue.