Improve example coverage of plotting module

[akaszynski]

About 50% of our docstrings in PyVista have examples. This is fairly good, especially considering that many of these objects are not publicly exposed.

However, for modules like pyvista.plotting.plotting, it would be great to see nearly 100% coverage considering how important it is to be able to demonstrate the individual methods of the Plotting class.

This is a great first issue since it doesn't involve changing the code base, just providing an example for some of our docstrings in plotting

Feel free to post questions here on how to get started if you're interested.

Note that many of these examples don't need to include plotter.show, and if they write files you can feel free to use the # doctest:+SKIP directive

Name                                         Docstrings     Missed   Covered
----------------------------------------------------------------------------
pyvista.plotting.plotting                           155        110     29.0%

Some easy ones

• [x] Plotter.export_vtkjs
• [ ] Plotter.fly_to
• [x] Plotter.remove_legend
• [x] Plotter.save_graphic
• [x] Plotter.add_point_labels
• [x] Plotter.add_lines
• [x] Plotter.add_text
• [x] Plotter.add_legend (needs to be fixed, plots aren't great)
• [ ] Plotter.add_point_scalar_labels
• [x] Plotter.add_volume
• [ ] Plotter.increment_point_size_and_line_width
• [x] Plotter.link_views
• [x] remove_background_image
• [x] remove_bounds_axes
• [x] Plotter.remove_scalar_bar
• [ ] Plotter.render
• [ ] Plotter.reset_camera_clipping_range
• [x] Plotter.set_environment_texture
• [x] Plotter.show_axes_all
• [x] Plotter.show_grid
• [x] Plotter.view_xy
• [x] Plotter.view_xz
• [x] Plotter.view_yx
• [x] Plotter.view_yz
• [x] Plotter.view_zx
• [x] Plotter.view_zy

Attributes:

• [x] Plotter.background_color
• [x] Plotter.bounds
• [ ] Plotter.camera
• [x] Plotter.camera_position
• [ ] Plotter.center
• [ ] Plotter.image

Harder ones

• [ ] Plotter.add_actor

In widgets.py but exposed in Plotter

• [ ] add_box_widget
• [ ] add_checkbox_button_widget
• [ ] add_line_widget
• [ ] add_mesh_clip_box
• [ ] add_mesh_clip_plane
• [ ] add_mesh_isovalue
• [ ] add_mesh_slice
• [ ] add_mesh_slice_orthogonal
• [ ] add_mesh_slice_spline
• [ ] add_mesh_threshold
• [ ] add_plane_widget
• [ ] add_sphere_widget
• [ ] add_spline_widget
• [ ] add_text_slider_widget

Note that if we use the @wraps decorator, we need to make the changes to the docstring in the method being wrapped.

[AleenaSA]

Hi, this sounds interesting as a first contribution. Could you give me more pointers on how to begin?

[akaszynski]

Add an Examples section in one of the methods in the Plotter class. For example, add_text: https://github.com/pyvista/pyvista/blob/598fb020618a0bfa4803039768ce51be4fd5ca68/pyvista/plotting/plotting.py#L2925

See the other example sections like the one for add_background_image: https://github.com/pyvista/pyvista/blob/598fb020618a0bfa4803039768ce51be4fd5ca68/pyvista/plotting/plotting.py#L4193-L4200

Create a PR with just that new section and you'll be good to go.

[AleenaSA]

The PR for add_text is merged, shall I look into others mentioned above as well? Individual PRs are required or one consolidated one is fine?

[akaszynski]

The PR for add_text is merged, shall I look into others mentioned above as well? Individual PRs are required or one consolidated one is fine?

That would be great! You can do individual or get several in one depending on how ambitious you'd like.

[AleenaSA]

Hi, I have a couple of questions. In case of save_graphic and export_vtkjs what should be the file path given in the docstring examples? Also to remove_legend we'll have to first add legend and then call the remove method, right? or do we have an example where legend is already added?

[akaszynski]

In case of save_graphic and export_vtkjs what should be the file path given in the docstring examples?

Good question. This is a good case to use # doctest:+SKIP. We don't want to actually write any files, just to demonstrate usage (and show a cool plot) whenever possible. See:

https://github.com/pyvista/pyvista/blob/7a41ba4176429fd005c42203aac80d36f97d4255/pyvista/plotting/plotting.py#L355-L364

Also to remove_legend we'll have to first add legend and then call the remove method, right? or do we have an example where legend is already added?

Exactly. It's up to you if you want to show before/after plots like as in enable_shadows.

[adeak]

I've ticked out Plotter.add_volume(), thanks to @puripant, our newest contributor :tada:

[puripant]

I am planning to add a bunch about views in one PR. A few questions. For those that are simply wraps of renderer.py functions, I should add examples in renderer.py, right? And since many functions are similar, should I write all examples separately or, say, refer to one big example of many views?

[adeak]

I am planning to add a bunch about views in one PR.

Excellent!

For those that are simply wraps of renderer.py functions, I should add examples in renderer.py, right?

Right. But you can probably frame the examples in terms of Plotters, which is what users will be facing.

And since many functions are similar, should I write all examples separately or, say, refer to one big example of many views?

Ideally each docstring example should showcase that one method in context. It's OK if some methods have the same example where there's overlap, but the view_* methods sound mutually exclusive. "One big example of many views" sounds like something that could go in the Plotting section of the dedicated Examples, assuming we don't already have that.

[tkoyama010]

This is probably the BEST FIRST ISSUE. Thank you very much.