struggling with consulting the positional argument order here at the `py5_tools.animated_gif()`, scrolling horizontally

[hx2A]

I think I'm struggling with consulting the positional argument order here at the py5_tools.animated_gif(), scrolling horizontally.

Could we have each parameter name in its own line for those long signatures?

Originally posted by @villares in https://github.com/py5coding/py5generator/discussions/100#discussioncomment-3291773

[hx2A]

py5_tools.offline_frame_processing() is also ridiculous.

[hx2A]

I went through all the signatures to get an idea of how common this problem is. py5_tools.offline_frame_processing() does in fact have the longest signature, followed by render_frame_sequence(). Some of them have unexpected lengths, like remap(). Among methods with multiple signatures, apply_matrix() is the longest.

[hx2A]

render_frame_sequence(draw: Callable, width: int, height: int, renderer: str = Sketch.HIDDEN, *, limit: int = 1, setup: Callable = None, setup_args: tuple = None, setup_kwargs: dict = None, draw_args: tuple = None, draw_kwargs: dict = None, use_py5graphics: bool = False) -> list[PIL.ImageFile.ImageFile]

@villares , what do you think of the below signature to replace what is above?

render_frame_sequence(draw: Callable, width: int, height: int, renderer: str = Sketch.HIDDEN, *,
                      limit: int = 1, setup: Callable = None, setup_args: tuple = None,
                      setup_kwargs: dict = None, draw_args: tuple = None, draw_kwargs: dict = None,
                      use_py5graphics: bool = False) -> list[PIL.ImageFile.ImageFile]

This is that autopep8 would do:

render_frame_sequence(draw: Callable,
                      width: int,
                      height: int,
                      renderer: str = Sketch.HIDDEN,
                      *,
                      limit: int = 1,
                      setup: Callable = None,
                      setup_args: tuple = None,
                      setup_kwargs: dict = None,
                      draw_args: tuple = None,
                      draw_kwargs: dict = None,
                      use_py5graphics: bool = False) -> list[PIL.ImageFile.ImageFile]

This is what black would do:

render_frame_sequence(
    draw: Callable,
    width: int,
    height: int,
    renderer: str = Sketch.HIDDEN,
    *,
    limit: int = 1,
    setup: Callable = None,
    setup_args: tuple = None,
    setup_kwargs: dict = None,
    draw_args: tuple = None,
    draw_kwargs: dict = None,
    use_py5graphics: bool = False
) -> list[PIL.ImageFile.ImageFile]

autopep8 and black look nice when the functions are shown in isolation, but my fear is that for methods with multiple signatures like apply_matrix(), it will add a lot of vertical height to this section of each page.

[hx2A]

On the other hand, all of these 3 choices are better than the status quo. But there is a tradeoff between vertical height and horizontal scrolling.

[hx2A]

@villares , have a look at the signatures in the reference docs at http://py5dev.ixora.io. I rebuilt all of the reference docs with black as a signature formatter.

I'm not happy with what it did for apply_matrix(). There are 3 signatures and they all look different? But on the other hand, the status quo has problems, and maybe this has less things that aren't that great.

@tabreturn and @marcovicci, can you also have a look? I'd like to hear your opinions on signature formatting in the reference docs.

[hx2A]

Here's a link to every reference doc that will change. Except for apply_matrix() and a few others like ortho(), I don't see any much that I don't like. I can live with a few that look weird to me.

http://py5dev.ixora.io/reference/py5functions_create_font_file.html http://py5dev.ixora.io/reference/py5functions_register_image_conversion.html http://py5dev.ixora.io/reference/py5functions_render.html http://py5dev.ixora.io/reference/py5functions_render_frame.html http://py5dev.ixora.io/reference/py5functions_render_frame_sequence.html http://py5dev.ixora.io/reference/py5functions_render_sequence.html http://py5dev.ixora.io/reference/py5graphics_ambient_light.html http://py5dev.ixora.io/reference/py5graphics_apply_matrix.html http://py5dev.ixora.io/reference/py5graphics_arc.html http://py5dev.ixora.io/reference/py5graphics_bezier.html http://py5dev.ixora.io/reference/py5graphics_bezier_tangent.html http://py5dev.ixora.io/reference/py5graphics_bezier_vertex.html http://py5dev.ixora.io/reference/py5graphics_blend.html http://py5dev.ixora.io/reference/py5graphics_camera.html http://py5dev.ixora.io/reference/py5graphics_color_mode.html http://py5dev.ixora.io/reference/py5graphics_copy.html http://py5dev.ixora.io/reference/py5graphics_curve.html http://py5dev.ixora.io/reference/py5graphics_directional_light.html http://py5dev.ixora.io/reference/py5graphics_frustum.html http://py5dev.ixora.io/reference/py5graphics_image.html http://py5dev.ixora.io/reference/py5graphics_line.html http://py5dev.ixora.io/reference/py5graphics_ortho.html http://py5dev.ixora.io/reference/py5graphics_perspective.html http://py5dev.ixora.io/reference/py5graphics_point_light.html http://py5dev.ixora.io/reference/py5graphics_quad.html http://py5dev.ixora.io/reference/py5graphics_quadratic_vertex.html http://py5dev.ixora.io/reference/py5graphics_rect.html http://py5dev.ixora.io/reference/py5graphics_save.html http://py5dev.ixora.io/reference/py5graphics_set_np_pixels.html http://py5dev.ixora.io/reference/py5graphics_spot_light.html http://py5dev.ixora.io/reference/py5graphics_text.html http://py5dev.ixora.io/reference/py5graphics_triangle.html http://py5dev.ixora.io/reference/py5image_blend.html http://py5dev.ixora.io/reference/py5image_copy.html http://py5dev.ixora.io/reference/py5image_save.html http://py5dev.ixora.io/reference/py5image_set_np_pixels.html http://py5dev.ixora.io/reference/py5shape_apply_matrix.html http://py5dev.ixora.io/reference/py5shape_bezier_vertex.html http://py5dev.ixora.io/reference/py5shape_quadratic_vertex.html http://py5dev.ixora.io/reference/py5tools_animated_gif.html http://py5dev.ixora.io/reference/py5tools_capture_frames.html http://py5dev.ixora.io/reference/py5tools_offline_frame_processing.html http://py5dev.ixora.io/reference/py5tools_save_frames.html http://py5dev.ixora.io/reference/py5tools_screenshot.html http://py5dev.ixora.io/reference/py5tools_sketch_portal.html http://py5dev.ixora.io/reference/py5vector_angle_between.html http://py5dev.ixora.io/reference/py5vector_cross.html http://py5dev.ixora.io/reference/py5vector_dist.html http://py5dev.ixora.io/reference/py5vector_dot.html http://py5dev.ixora.io/reference/py5vector_lerp.html http://py5dev.ixora.io/reference/sketch_ambient_light.html http://py5dev.ixora.io/reference/sketch_apply_matrix.html http://py5dev.ixora.io/reference/sketch_arc.html http://py5dev.ixora.io/reference/sketch_atan2.html http://py5dev.ixora.io/reference/sketch_bezier.html http://py5dev.ixora.io/reference/sketch_bezier_tangent.html http://py5dev.ixora.io/reference/sketch_bezier_vertex.html http://py5dev.ixora.io/reference/sketch_blend.html http://py5dev.ixora.io/reference/sketch_camera.html http://py5dev.ixora.io/reference/sketch_color_mode.html http://py5dev.ixora.io/reference/sketch_constrain.html http://py5dev.ixora.io/reference/sketch_copy.html http://py5dev.ixora.io/reference/sketch_create_font.html http://py5dev.ixora.io/reference/sketch_create_image_from_numpy.html http://py5dev.ixora.io/reference/sketch_curve.html http://py5dev.ixora.io/reference/sketch_directional_light.html http://py5dev.ixora.io/reference/sketch_dist.html http://py5dev.ixora.io/reference/sketch_frustum.html http://py5dev.ixora.io/reference/sketch_image.html http://py5dev.ixora.io/reference/sketch_launch_promise_thread.html http://py5dev.ixora.io/reference/sketch_launch_repeating_thread.html http://py5dev.ixora.io/reference/sketch_launch_thread.html http://py5dev.ixora.io/reference/sketch_lerp.html http://py5dev.ixora.io/reference/sketch_line.html http://py5dev.ixora.io/reference/sketch_load_image.html http://py5dev.ixora.io/reference/sketch_mag.html http://py5dev.ixora.io/reference/sketch_noise.html http://py5dev.ixora.io/reference/sketch_norm.html http://py5dev.ixora.io/reference/sketch_ortho.html http://py5dev.ixora.io/reference/sketch_os_noise.html http://py5dev.ixora.io/reference/sketch_perspective.html http://py5dev.ixora.io/reference/sketch_point_light.html http://py5dev.ixora.io/reference/sketch_println.html http://py5dev.ixora.io/reference/sketch_quad.html http://py5dev.ixora.io/reference/sketch_quadratic_vertex.html http://py5dev.ixora.io/reference/sketch_random_choice.html http://py5dev.ixora.io/reference/sketch_rect.html http://py5dev.ixora.io/reference/sketch_remap.html http://py5dev.ixora.io/reference/sketch_run_sketch.html http://py5dev.ixora.io/reference/sketch_save.html http://py5dev.ixora.io/reference/sketch_save_frame.html http://py5dev.ixora.io/reference/sketch_save_json.html http://py5dev.ixora.io/reference/sketch_select_folder.html http://py5dev.ixora.io/reference/sketch_select_input.html http://py5dev.ixora.io/reference/sketch_select_output.html http://py5dev.ixora.io/reference/sketch_set_np_pixels.html http://py5dev.ixora.io/reference/sketch_spot_light.html http://py5dev.ixora.io/reference/sketch_sqrt.html http://py5dev.ixora.io/reference/sketch_text.html http://py5dev.ixora.io/reference/sketch_triangle.html

[hx2A]

I made it so that if there are multiple signatures and at least one of them has a signature that spans multiple lines, it will add a blank line between signatures. I think this looks better than crowding them together, especially for signatures like apply_matrix(), where the 3 signatures look a bit different.

I didn't think I would like this approach but now that I see it in action, I think it works for me.

[hx2A]

Here's a crazy idea that builds on this thread: what if we combined the signatures and parameter sections? So for example, for os_noise(), the signature section would become:

os_noise(
    x: Union[float, npt.NDArray],  # x-coordinate in noise space
    y: Union[float, npt.NDArray],  # y-coordinate in noise space
    /
) -> Union[float, npt.NDArray]

os_noise(
    x: Union[float, npt.NDArray],  # x-coordinate in noise space
    y: Union[float, npt.NDArray],  # y-coordinate in noise space
    z: Union[float, npt.NDArray],  # z-coordinate in noise space
    /,
) -> Union[float, npt.NDArray]

os_noise(
    x: Union[float, npt.NDArray],  # x-coordinate in noise space
    y: Union[float, npt.NDArray],  # y-coordinate in noise space
    z: Union[float, npt.NDArray],  # z-coordinate in noise space
    w: Union[float, npt.NDArray],  # w-coordinate in noise space
    /,
) -> Union[float, npt.NDArray]

With this approach, the parameter section would go away.

[hx2A]

@villares , this also addresses an issue you raised a long time ago about why the parameters are alphabetized, and if they can be ordered differently.

[hx2A]

For some of them like Py5Shader.set() there would be a lot of repeating of the same parameter name. But the way it is now, you have to keep scrolling up and down to make sense of it.

blend() and text() would also be a bit odd, but I think overall this would work.

[hx2A]

So py5 has 551 methods and a total of 874 signatures. Writing code that documents all of the signatures using this new approach was an enormous amount of work! There are many edge cases...anyhow, I have it working now. @villares, Head over to http://py5dev.ixora.io/ and let me know what you think.

Some of them, like apply_matrix() look poor because every variable has the same description. I can correct that separately. Py5Shader.set() is a bit unwieldy, but how it is currently isn't that great either. I prefer the status quo for this one, but that's partly because I don't need to scroll to read the variable descriptions. The vast majority of these seem better, so I think this is an improvement.

[hx2A]

I made the code changes and will push the new website to prod in a moment

[hx2A]

Done!

[tabreturn]

Great work, @hx2A. Sorry -- I'm a bit late to the party on this one; I've been on vacation (road trip), and I'll be back in a few days. IMO, you've devised and opted for the most elegant solution 👍

[hx2A]

Thanks, @tabreturn ! As you can see, it took a lot of thought to arrive at this. I'm happy with the result.

Most likely I am doing a release in a few days.