Opened 5 years ago

Closed 5 years ago

Last modified 5 years ago

#25159 closed Cleanup/optimization (fixed)

Remove brackets from method/function signatures in docs

Reported by: Tim Graham Owned by: Tim Graham
Component: Documentation Version: 1.8
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

According to the spinx docs, "For functions with optional parameters that don’t have default values (typically functions implemented in C extension modules without keyword argument support), you can use brackets to specify the optional parts". Not sure how our docs got in the habit of using brackets, but it doesn't seem like we should be doing that.

Brackets should be removed from things like:

.. function:: create_test_db([verbosity=1, autoclobber=False, serialize=True, keepdb=False])

and missing kwarg defaults should be added in places like:

.. function:: password_reset_confirm(request[, uidb64, token, template_name, token_generator, set_password_form, post_reset_redirect, current_app, extra_context])

Find the places to update with grep -rI "\[" * | grep 'function::' and grep -rI "\[" * | grep 'method::'.

Change History (6)

comment:1 Changed 5 years ago by hellbeast

Owner: changed from nobody to hellbeast
Status: newassigned

comment:2 Changed 5 years ago by hellbeast

Owner: hellbeast deleted
Status: assignednew

comment:3 Changed 5 years ago by Tim Graham

Owner: set to Tim Graham
Status: newassigned

comment:4 Changed 5 years ago by Tim Graham

Has patch: set

comment:5 Changed 5 years ago by Tim Graham <timograham@…>

Resolution: fixed
Status: assignedclosed

In 87d5508:

Fixed #25159 -- Removed brackets from class/function/method signatures in docs.

Thanks hellbeast for the initial patch.

comment:6 Changed 5 years ago by Tim Graham <timograham@…>

In a66d843:

[1.8.x] Fixed #25159 -- Removed brackets from class/function/method signatures in docs.

Thanks hellbeast for the initial patch.

Backport of 87d55081ea398c65b2503d22ed3907a9175ec729 from master

Note: See TracTickets for help on using tickets.
Back to Top