Improve documentation - Githubissues

flaviorangel commented 5 years ago

This issue is related to issue #223. In order to publish in Joss, we need to improve our documentation. Every function/method must be documented, including inputs, outputs, and an example. I'll be listing here the functions/methods that need their documentation to be improved (and why).

flaviorangel commented 5 years ago

In rotor_assembly.py:

[x] eq (lacks documentation);
[x] w (lacks documentation);
[x] run_modal (lacks documentation);
[x] whirl_direction (lacks output and example);
[x] whirl_values (lacks output and example);
[ ] orbit (lacks documentation);
[x] _lti (lacks output and example);
[x] transfer_matrix (lacks documentation);
[x] run_freq_response (lacks example);
[x] run_forced_response (lacks documentation);
[x] _unbalance_force (lacks input, output, and example);
[x] unbalance_response (lacks example);
[x] time_response (lacks example);
[x] _plot_rotor_matplotlib (lacks documentation);
[x] _plot_rotor_bokeh (lacks example);
[x] run_mode_shapes (lacks documentation);
[x] plot_ucs (lacks example);
[x] plot_level1 (lacks example);
[x] run_time_response (lacks example);
[x] save_mat (lacks input and example);
[x] save (lacks example);
[x] load (lacks example);
[x] available_rotors (lacks documentation);
[x] remove (lacks documentation);
[x] run_static (lacks example);
[x] from_section (lacks output);
[x] rotor_regions (lacks documentation);
[x] MAC (lacks input, output, and example);
[x] MAC_modes (lacks input, output, and example);
[x] whirl (lacks input, output, and example);
[x] whirl_to_cmap (lacks input, output, and example).

flaviorangel commented 5 years ago

In bearing_seal_element.py:

[ ] class _Coefficient (lacks documentation, along with its methods)
[ ] class _Stiffness_Coefficient (lacks documentation, along with its plot method)
[ ] class _Damping_Coefficient (lacks documentation, along with its plot method)

From BearingElement class:

[x] repr (lacks documentation)
[x] eq (lacks documentation)
[x] save (lacks documentation)
[x] load (lacks documentation)
[x] dof_mapping (lacks documentation)
[x] M (lacks documentation)
[x] K (lacks documentation)
[x] C (lacks documentation)
[x] G (lacks documentation)
[ ] patch (lacks example)
[ ] bokeh_patch (lacks example)
[x] table_to_toml (lacks example)
[x] from_table (lacks example)
[x] from_fluid_flow (lacks example)

From class SealElement

[x] class SealElement (lacks documentation)
[ ] patch (lacks example; also, arguments don't match documentation input)
[ ] bokeh_patch (lacks example; also, arguments don't match documentation input)

flaviorangel commented 5 years ago

In disk_element.py:

[x] eq (lacks documentation)
[x] repr (lacks documentation)
[x] save (lacks documentation)
[x] load (lacks documentation)
[x] dof_mapping (lacks documentation)
[x] K (lacks documentation)
[x] C (lacks documentation)
[ ] patch (lacks example; also, arguments don't match documentation input)
[ ] bokeh_patch (lacks example; also, arguments don't match documentation input)
[x] from_table (lacks example)

flaviorangel commented 5 years ago

In element.py:

[x] save (lacks documentation)
[x] load (lacks documentation)
[x] C (lacks inputs)
[x] K (lacks inputs)
[x] load_data (lacks documentation)
[x] dump_data (lacks documentation)

flaviorangel commented 5 years ago

In materials.py:

[ ] eq (lacks documentation)
[ ] repr (lacks documentation)
[ ] str (lacks documentation)
[ ] dump_data (lacks documentation)
[ ] load_data (lacks documentation)
[ ] use_material (lacks documentation)
[ ] remove_material (lacks documentation)
[ ] available_materials (lacks documentation)
[ ] save_material (lacks documentation)

flaviorangel commented 5 years ago

In results.py:

From class Results:

[ ] __array_finalize__ (lacks documentation)
[ ] reduce (lacks documentation)
[ ] setstate (lacks documentation)
[ ] save (lacks documentation)
[ ] plot (lacks documentation)

From class CampbellResults:

[x] class CampbellResults (lacks documentation)
[x] _plot_matplotlib (lacks documentation)
[x] _plot_bokeh (lacks documentation)
[x] plot (lacks example; also, arguments don't match documentation input)

From class FrequencyResponseResults

[x] class FrequencyResponseResults (lacks documentation)
[x] plot_magnitude_matplotlib (lacks example; also, arguments don't match documentation input)
[x] plot_magnitude_bokeh (lacks example; also, arguments don't match documentation input)
[x] plot_phase_matplotlib (lacks example)
[x] plot_phase_bokeh (lacks example; also, arguments don't match documentation input)
[x] _plot_matplotlib (lacks example)
[x] _plot_bokeh (lacks example)
[x] plot (lacks example; also, arguments don't match documentation input)
[x] plot_freq_response_grid (lacks example)

From class ForcedResponseResults

[x] class ForcedResponseResults (lacks documentation)
[x] plot_magnitude_matplotlib (lacks example)
[x] plot_magnitude_bokeh (lacks example)
[x] plot_phase_matplotlib (lacks example)
[x] plot_phase_bokeh (lacks example)
[x] _plot_matplotlib (lacks documentation)
[x] _plot_bokeh (lacks documentation)
[x] plot (lacks example)

From class ModeShapeResults:

[x] class ModeShapeResults (lacks documentation)
[x] plot (lacks documentation)

From class StaticResults:

[x] class StaticResults (lacks documentation)
[x] plot (lacks example)

From class ConvergenceResults:

[x] class ConvergenceResults (lacks documentation)
[x] plot (lacks example)

From class TimeResponseResults:

[x] class TimeResponseResults (lacks documentation)
[x] _plot_matplotlib (lacks documentation)
[x] _plot_bokeh (lacks documentation)
[x] plot (lacks example; also, arguments don't match documentation input)

flaviorangel commented 5 years ago

In shaft_element.py:

From class ShaftElement:

[x] eq (lacks documentation)
[x] save (lacks documentation)
[x] load (lacks documentation)
[ ] from_table (lacks example)
[x] n (lacks documentation)
[x] dof_mapping (lacks documentation)
[x] repr (lacks documentation)
[x] str (lacks documentation)
[ ] patch (lacks example; also, arguments don't match documentation input)
[ ] bokeh_patch (lacks example; also, arguments don't match documentation input)

From class ShaftTaperedElement:

[x] eq (lacks documentation)
[x] save (lacks documentation)
[x] load (lacks documentation)
[x] n (lacks documentation)
[x] dof_mapping (lacks documentation)
[x] repr (lacks documentation)
[x] str (lacks documentation)
[x] C (lacks example)
[ ] patch (lacks example; also, arguments don't match documentation input)
[ ] bokeh_patch (lacks example; also, arguments don't match documentation input)

flaviorangel commented 5 years ago

In utils.py:

[x] read_table_file (lacks example)

flaviorangel commented 5 years ago

In fluid_flow.py:

[x] calculate_pressure_matrix_analytical (lacks output and example)
[x] calculate_coefficients (lacks example)
[x] mounting_matrix (lacks example)
[x] resolves_matrix (lacks example)
[x] calculate_pressure_matrix_numerical (lacks output and example)
[x] internal_radius_function (lacks example)
[x] external_radius_function (lacks example)
[x] get_rotor_load (lacks example)
[x] modified_sommerfeld_number (lacks example)
[x] sommerfeld_number (lacks example)
[x] calculate_eccentricity_ratio (lacks example)
[x] get_analytical_stiffness_matrix (lacks example)
[x] get_analytical_damping_matrix (lacks example)
[x] plot_eccentricity (lacks example)
[x] plot_pressure_z (lacks example)
[x] plot_shape (lacks example)
[x] plot_pressure_theta (lacks example)
[x] matplot_eccentricity (lacks example)
[x] matplot_pressure_z (lacks example)
[x] matplot_shape (lacks example)
[x] matplot_pressure_theta_cylindrical (lacks example)
[x] matplot_pressure_theta (lacks example)

flaviorangel commented 5 years ago

Because there are so many different files to work on, and more than one person working on them, we agreed to let the others know in which file we are working on. So I'm on bearing_seal_element.py

rodrigomoliveira1 commented 5 years ago

I'm working on rotor_assembly.py

flaviorangel commented 5 years ago

So I'm on bearing_seal_element.py

bearing_seal_element.py is almost done. A few functions still need attention though: the ones from _Coefficient class, as I wasn't sure on how to explain them; and the "patch" functions, which I found it hard to create an example to.

I'll be working on disk_element.py

rodrigomoliveira1 commented 5 years ago

I've been working on results.py documentation and I wanted to raise two issues:

I did not improved anything in class Results because it's obsolete and it's going to be removed soon.
I did not implemented any example because if we calls rotor_example() in results.py, we get a recursive error. We cannot import rotor_assembly.py in results.py if rotor_assembly.py already imports results.py

flaviorangel commented 5 years ago

I'll be working on element.py. There is an open PR for materials.py, so we got it all covered.

flaviorangel commented 5 years ago

I did not improved anything in class Results because it's obsolete and it's going to be removed soon.

Okay. Once it is removed, we no longer have to worry about it.

I did not implemented any example because if we calls rotor_example() in results.py, we get a recursive error. We cannot import rotor_assembly.py in results.py if rotor_assembly.py already imports results.py

This is a tricky one. I'm not sure how we should handle this. Maybe we could leave it without examples and see if the reviewers will require some.

raphaeltimbo commented 4 years ago

I believe we can close this for now.

petrobras / ross

Improve documentation #236