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

Summary tables for argparse add_argument options #58058

Closed
ncoghlan opened this issue Jan 24, 2012 · 23 comments
Closed

Summary tables for argparse add_argument options #58058

ncoghlan opened this issue Jan 24, 2012 · 23 comments
Assignees
Labels
3.7 (EOL) end of life 3.8 (EOL) end of life docs Documentation in the Doc dir type-feature A feature request or enhancement

Comments

@ncoghlan
Copy link
Contributor

ncoghlan commented Jan 24, 2012

BPO 13850
Nosy @rhettinger, @ncoghlan, @ezio-melotti, @merwok, @bitdancer, @masklinn, @berkerpeksag, @matrixise
PRs
  • bpo-13850: Add summary tables for argparse add_argument options #12070
  • Files
  • argparse-actions-matrix: matrix of actions for add_argument parameters
  • argparse-actions-matrix-v2
  • patch13850v0.patch: first version of patch
  • Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

    Show more details

    GitHub fields:

    assignee = None
    closed_at = None
    created_at = <Date 2012-01-24.05:54:57.629>
    labels = ['3.8', 'type-feature', '3.7', 'docs']
    title = 'Summary tables for argparse add_argument options'
    updated_at = <Date 2019-03-24.06:00:34.485>
    user = 'https://github.com/ncoghlan'

    bugs.python.org fields:

    activity = <Date 2019-03-24.06:00:34.485>
    actor = 'matrixise'
    assignee = 'docs@python'
    closed = False
    closed_date = None
    closer = None
    components = ['Documentation']
    creation = <Date 2012-01-24.05:54:57.629>
    creator = 'ncoghlan'
    dependencies = []
    files = ['25018', '38917', '38966']
    hgrepos = []
    issue_num = 13850
    keywords = ['patch']
    message_count = 22.0
    messages = ['151880', '151881', '151889', '151891', '151895', '151918', '151926', '151928', '151930', '156760', '156762', '159565', '223250', '240616', '240617', '240752', '240816', '240817', '336768', '336805', '336814', '338719']
    nosy_count = 12.0
    nosy_names = ['rhettinger', 'ncoghlan', 'bethard', 'ezio.melotti', 'eric.araujo', 'r.david.murray', 'xmorel', 'docs@python', 'tshepang', 'berker.peksag', 'matrixise', 'ttz']
    pr_nums = ['12070']
    priority = 'normal'
    resolution = None
    stage = 'patch review'
    status = 'open'
    superseder = None
    type = 'enhancement'
    url = 'https://bugs.python.org/issue13850'
    versions = ['Python 2.7', 'Python 3.7', 'Python 3.8']

    Linked PRs

    @ncoghlan
    Copy link
    Contributor Author

    With the current argparse docs, it's very hard to get a quick reminder of how to spell the various parameters for add_argument, and just what they do. This issue suggests adding a "Quick Reference" section for add_argument, with the following elements:

    1. Summary table with a one line description of each parameter
    2. Summary table with a one line description of each alternative for the "action" parameter (including noting which other parameters are potentially relevant, such as 'choices' and 'metavar' for 'store' and 'const' for 'store_const')
    3. Summary table with a one line description of each alternative for the "nargs" parameter

    @ncoghlan ncoghlan added the docs Documentation in the Doc dir label Jan 24, 2012
    @ncoghlan
    Copy link
    Contributor Author

    Looking at the docs, a 4th table in the quick reference section would be useful: the parameters for ArgumentParser itself.

    Note that the ArgumentParser and add_arguments() parameters are already summarised in their respective entries, but there are currently no summaries at all for the possible "action" and "nargs" values

    @masklinn
    Copy link
    Mannequin

    masklinn mannequin commented Jan 24, 2012

    Creating the tables should not be too hard, especially using e.g. org-mode, but:

    1. Where should those tables live? The argparse documentation is pretty big and there's no completely obvious place. I would guess table 1. could just replace the list of arguments in http://docs.python.org/py3k/library/argparse.html#the-add-argument-method but things are harder for action (as many actions have examples as well, so the listing can't just be replaced) and for nargs

    2. If the current lists of argument: role (in ArgumentParser and add_argument) are not sufficient, why would a table somehow be considering it would add visual clutter (table borders, for instance)?

    Maybe a good alternative would be to build a table style for info fields lists and to use :param: wherever that belongs?

    Or the doc could be split into a "quickstart" with just a listing of arguments and a *very simple* example or two, and then the exhaustive documentation, which could even be a separate document?

    @ncoghlan
    Copy link
    Contributor Author

    My specific suggestion is to have a dedicated "Quick Reference" section before the first example.

    This section would be aimed at two groups of people:

    • those wanting a quick overview of the features argparse offers them ("This looks complicated, what can it do for me?")
    • those wanting a reminder of the exact spelling of various items ("I know what I want to do, and I know argparse can do it because I've done it before, but how do I tell argparse exactly what I want?")

    Since the heart of argparse is the ability to map arguments to actions, I'd suggest the quick reference section actually lead with a table of "actions" that argparse natively supports, along with a final entry pointing to the information on custom actions (i.e. subclasses of argparse.Action).

    Likely columns for this first table: Action Name, Description, Parameters

    The "Parameters" column would span multiple lines, with one parameter and a brief description of the parameter on each line.

    The second table could then just be a short summary of the various 'nargs' values.

    Repeating the list of parameters to ArgumentParser in the quick reference section probably isn't necessary, and the short parameter descriptions in the actions table should suffice for add_argument().

    @masklinn
    Copy link
    Mannequin

    masklinn mannequin commented Jan 24, 2012

    My specific suggestion is to have a dedicated "Quick Reference" section before the first example.

    OK, that looks like a good plan.

    @bethard
    Copy link
    Mannequin

    bethard mannequin commented Jan 24, 2012

    Sounds like an excellent plan to me too.

    @masklinn
    Copy link
    Mannequin

    masklinn mannequin commented Jan 24, 2012

    The "Parameters" column would span multiple lines, with one parameter and a brief description of the parameter on each line.

    I started looking into that, and it turns out that's more annoying than expected: a bunch of parameters are shared by many (to all) actions, leading to lots of duplications in the table. And the full matrix of actions to parameters is not really explained in the doc.

    In fact, I'm coming around to thinking a matrix of the interaction between actions and arguments could be better and clearer than a table of actions with parameters bunched together at the end.

    In any case, it would certainly be more maintainable... except for rST not really having support for attributes on data tables, and (as far as I can tell) can't handle horizontal headers.

    @ncoghlan
    Copy link
    Contributor Author

    Having a second table of "Applicable Parameters" could definitely work. I don't think the "no horizontal headers" limitation should be a big problem - the matrix should be readable even if the action names are just listed in an ordinary column.

    @rhettinger
    Copy link
    Contributor

    +1 from me. The docs in their present form are a great tutorial but are a total failure as a quick reference.

    Besides having table of parameters, it may also be worthwhile to move some of the examples to a HOWTO document (much as was done with the logging package).

    @masklinn
    Copy link
    Mannequin

    masklinn mannequin commented Mar 25, 2012

    Had some time to play with this today, here's a draft matrix of actions and add_argument parameters which is pretty readable, but:

    • It's incredibly not helpful for people who don't know argparse
    • I tried adding effects descriptions in the cells instead of mere tick marks, the table becomes completely unreadable. I added a note directive below the table but it only lists a few really important/weird things, and it really won't scale beyond the current 3 items (which might already be too much)
    • I completely removed the help action from the table as it's unlikely anyone will want to override it (and its row was completely blank)
    • Hyperlinking and cross-linking (to the params, the actions, footnotes) would probably be a good idea, although it would definitely make the "raw text" (in-rst)

    I also tried my hand at formatting nargs, but I don't see it as much clearer than http://docs.python.org/library/argparse.html#nargs without the examples, it's still just a mapping from a value to a behavior. I think the result would be just as good if the current nargs description was made into a definition list (in effect, it already is one emulated through an unordered list) and the examples were moved or removed.

    @masklinn
    Copy link
    Mannequin

    masklinn mannequin commented Mar 25, 2012

    completion for list item 4:

    although it would definitely make the "raw text" (in-rst) much harder to read compared to the current table (which can be used from the rst source without compiling)

    @ezio-melotti
    Copy link
    Member

    • It's incredibly not helpful for people who don't know argparse

    Indeed. Maybe this should be moved down in the page, and possibly provide a link to the top (see e.g. the unittest doc 0 and the link on top to jump to the list of assert methods). Once people know it's there they will find it easily, but opening the doc with this table is a bit confusing IMHO. Adding a couple of line to explain what the table is for might also help.

    • I tried adding effects descriptions in the cells instead of mere
      tick marks, the table becomes completely unreadable.

    In the rst source only latin-1 chars are allowed (otherwise make pdf breaks), so you should replace the tick marks with something else (e.g. "x" or "yes"/"no").

    I added a note directive below the table but it only lists a few
    really important/weird things, and it really won't scale beyond the
    current 3 items (which might already be too much)

    You can also add notes numbers just next to the "x"s and add a description below [1]. This could be applied to the "const" column as well if you want to save some horizontal space. If you want to save even more space you could remove the version row/column and add a note about it.

    • I completely removed the help action from the table as it's
      unlikely anyone will want to override it (and its row was completely blank)

    Maybe you could add a note about this too.

    • Hyperlinking and cross-linking (to the params, the actions,
      footnotes) would probably be a good idea, although it would
      definitely make the "raw text" (in-rst)

    This might be useful (I did it in the assert methods' tables in the unittest doc 0), and having links in the HTML probably outweighs the fact that the rst source becomes less readable.

    Note that (depending on what you change), you might be able to use the lightweight syntax for tables if you prefer.

    [1]: e.g. http://docs.python.org/library/stdtypes.html#numeric-types-int-float-long-complex

    @ezio-melotti ezio-melotti added the type-feature A feature request or enhancement label Apr 29, 2012
    @BreamoreBoy
    Copy link
    Mannequin

    BreamoreBoy mannequin commented Jul 16, 2014

    At a quick glance the patch looks okay to me so as there's been a lot of positive comments can we have a formal patch review please.

    @matrixise
    Copy link
    Member

    Just updated this patch with "x" instead of the unicode character.

    @matrixise
    Copy link
    Member

    On 13 Apr 2015, at 10:56, Stéphane Wirtel wrote:

    Stéphane Wirtel added the comment:

    Just updated this patch with "x" instead of the unicode character.

    Sorry bad patch, I have read the last comment (“replace by x or
    “yes/no”) and not the other comments.

    @ttz
    Copy link
    Mannequin

    ttz mannequin commented Apr 13, 2015

    Created Quick Reference table subsection under the add_argument() method section - used the table originally created by xmorel, replacing ticks with 'x' and adding links to the sections in the documentation for each parameter names. Removed the 'version' column and row as that wasn't adding much info.

    There is also a link to the quick reference subsection at the top of the page.

    @bitdancer
    Copy link
    Member

    I think it would be better to move the summary table to the end (just before the Action section), and add another link to the summary to the sentence "The following sections describe how each of these are used." That is, follow that sentence with something like 'a summary table of the relevance of each paramter to the various possible actions is given at the end of the section', with a link on summary table.

    Otherwise, the patch looks good to me.

    @matrixise
    Copy link
    Member

    Hi all,

    If you think the patch is ok, please merge it, we will close this issue.

    Thanks

    @matrixise
    Copy link
    Member

    just for 2.7, 3.7 & 3.8 because they are in bugfix mode.

    @matrixise matrixise added 3.7 (EOL) end of life 3.8 (EOL) end of life labels Feb 27, 2019
    @rhettinger
    Copy link
    Contributor

    I like the idea of having various summary tables for argparse, but the one in the PR isn't visually attractive or self-explanatory.

    @matrixise
    Copy link
    Member

    Hi @Raymond,

    Yep, I understand about the "look", I have seen the result after the build of the doc but the patch was like that and I did not want to change the initial patch.

    Would you suggest one layout and I could update the PR with your recommendations?

    Thanks for your review

    @matrixise
    Copy link
    Member

    I close my PR, if anyone wants to submit an other PR, feel free to do it.

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    @erlend-aasland erlend-aasland moved this to Features in Argparse issues May 19, 2022
    @erlend-aasland erlend-aasland moved this from Features to Doc issues in Argparse issues May 19, 2022
    @savannahostrowski savannahostrowski self-assigned this Sep 18, 2024
    savannahostrowski added a commit to savannahostrowski/cpython that referenced this issue Sep 24, 2024
    emilyemorehouse added a commit to lysnikolaou/cpython that referenced this issue Sep 26, 2024
    * main: (69 commits)
      Add "annotate" SET_FUNCTION_ATTRIBUTE bit to dis. (python#124566)
      pythongh-124412: Add helpers for converting annotations to source format (python#124551)
      pythongh-119180: Disallow instantiation of ConstEvaluator objects (python#124561)
      For-else deserves its own section in the tutorial (python#123946)
      Add 3.13 as a version option to the crash issue template (python#124560)
      pythongh-123242: Note that type.__annotations__ may not exist (python#124557)
      pythongh-119180: Make FORWARDREF format look at __annotations__ first (python#124479)
      pythonGH-58058: Add quick reference for `ArgumentParser` to argparse docs (pythongh-124227)
      pythongh-41431: Add `datetime.time.strptime()` and `datetime.date.strptime()` (python#120752)
      pythongh-102450: Add ISO-8601 alternative for midnight to `fromisoformat()` calls. (python#105856)
      pythongh-124370: Add "howto" for free-threaded Python (python#124371)
      pythongh-121277: Allow `.. versionadded:: next` in docs (pythonGH-121278)
      pythongh-119400:  make_ssl_certs: update reference test data automatically, pass in expiration dates as parameters python#119400  (pythonGH-119401)
      pythongh-119180: Avoid going through AST and eval() when possible in annotationlib (python#124337)
      pythongh-124448: Update Windows builds to use Tcl/Tk 8.6.15 (pythonGH-124449)
      pythongh-123884 Tee of tee was not producing n independent iterators (pythongh-124490)
      pythongh-124378: Update test_ttk for Tcl/Tk 8.6.15 (pythonGH-124542)
      pythongh-124513: Check args in framelocalsproxy_new() (python#124515)
      pythongh-101100: Add a table of class attributes to the "Custom classes" section of the data model docs (python#124480)
      Doc: Use ``major.minor`` for documentation distribution archive filenames (python#124489)
      ...
    @savannahostrowski
    Copy link
    Member

    This is can be closed as completed now as both #124227 and #91726 have been merged.

    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Labels
    3.7 (EOL) end of life 3.8 (EOL) end of life docs Documentation in the Doc dir type-feature A feature request or enhancement
    Projects
    Status: Doc issues
    Development

    No branches or pull requests

    6 participants