Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Error rendering docstrings #202

Open
yiquintero opened this issue Dec 13, 2024 · 2 comments
Open

Error rendering docstrings #202

yiquintero opened this issue Dec 13, 2024 · 2 comments
Labels
documentation Suggests that documentation needs enriching

Comments

@yiquintero
Copy link
Contributor

yiquintero commented Dec 13, 2024

Description

The docstrings for the functions listed below are incorrectly rendered by Sphinx. The issue occurs when building the documentation locally using tudat-multidoc (tudat CLI) or the new method introduced as part of the 2024 updates to the tudatpy API documentation workflow. The docstrings are also rendered incorrectly on the API Reference website.

The error is the same in all cases: a reference to binary object address is included in the signature of the function, which is auto-generated by Sphinx. See the image below for an example.
image

Steps to reproduce

  1. Build tudatpy: Clone the tudat-bundle repo. Checkout the develop branch of tudat & tudatpy. Build tudatpy following the instructions in the readme file of tudat-bundle.
  2. Build the documentation: With the tudat-bundle conda env used in 1 still activated, build the docs locally by going to tudat-bundle/tudatpy/docs/ and running the command make html
  3. Explore the docs: Open the file tudatpy/docs/build/html/index.html with a web browser and search for one of the functions listed below.

Problematic Functions

Ephemeris

List of Functions
  1. interpolated_spice
  2. tabulated_from_existing

image

Estimation

List of Functions
  1. add_dependent_variable
  2. compatible_dependent_variable_settings
  3. compatible_dependent_variables_list
  4. concatenated_dependent_variable
  5. dependent_variable
  6. dependent_variable_history
  7. dependent_variable_history_per_set
  8. filter_observations
  9. get_bodies_in_link_ends
  10. get_computed_observations
  11. get_concatenated_computed_observations
  12. get_concatenated_float_observation_times
  13. get_concatenated_observation_times
  14. get_concatenated_observations
  15. get_concatenated_observations_and_times
  16. get_concatenated_residuals
  17. get_concatenated_weights
  18. get_mean_residuals
  19. get_observable_types
  20. get_observation_times
  21. get_observations
  22. get_observations_and_times
  23. get_reference_points_in_link_ends
  24. get_residuals
  25. get_rms_residuals
  26. get_single_observation_sets
  27. get_time_bounds_list
  28. get_time_bounds_per_set
  29. get_weights
  30. set_constant_weight (x2)
  31. set_reference_point (x2)
  32. set_reference_points
  33. set_tabulated_weights
  34. split_observation_sets
  35. EstimationInput constructor

Observation

List of Functions
  1. two_way_doppler_averaged
  2. one_way_range
  3. n_way_range
  4. two_way_range
  5. angular position
  6. relative_angular_position
  7. one_way_doppler_instantaneous
  8. one way doppler averaged
  9. n_way_doppler_averaged
  10. n_way_doppler_averaged_from_one_way_links

image

Propagator

List of Functions
  1. hybrid_arc
  2. translational
  3. rotational
  4. mass
  5. multitype
  6. multi_arc

image

@yiquintero yiquintero added the documentation Suggests that documentation needs enriching label Dec 13, 2024
@larshinueber
Copy link
Contributor

Hi all,

Based on the pybind docs this can be resolved using py::arg_v and manually specifying the default argument as string.
For the ephemeris, this would look as follows:
Image

However, this breaks a bit with the current way of instantiating interpolator settings (or settings in general), since they are typically not created through the init method of the class itself, but through a factory function.
Translating the instantiation from the init method to the factory function notation does not seem like a better option, since it would mean that the developer/person documenting the function has to reverse engineer the factory function and use it in the docstring, which seems very error-prone.

What are your thoughts?

@DominicDirkx
Copy link
Member

Thanks for figuring out a potential way to solve this!

As I understand it, we then have three options, keeping the following in mind:

Translating the instantiation from the init method to the factory function notation does not seem like a better option, since it would mean that the developer/person documenting the function has to reverse engineer the factory function and use it in the docstring, which seems very error-prone

  1. Have the C++-y default arguments, which can look horrible and don't really add any information to the user
  2. Use the init function of the objects, which typically us not used/exposed
  3. Use the factory function, which would need to be correctly hard-coded as a string by the developer.

Right?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Suggests that documentation needs enriching
Projects
None yet
Development

No branches or pull requests

3 participants