Include Python native docstrings on the API docs website

[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.

• [x] Determine the code block responsible for including the python native docs to the API docs page
• [x] Make changes to include the python native docs
• [x] build and test rendering of python native docs locally
• [x] 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.

NOTE

Above mentioned proof of concept was further modified to match the new requirements. Scroll to the bottom of this issue to read the latest updates.

[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 144-render-python-native-docs
• 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/144-render-python-native-docs/

Points to address going forward

• Python files in tudatpy/data/ could not be rendered on the API docs website in the same way as the python files in tudatpy/mumerical_simulation/environment_setup/ephemeris and gravity_field because of the difference in the folder structure.