prompt-toolkit / prompt-toolkit/python-prompt-toolkit

Numerous functions missing from the documentation/docs

Open
#821 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
10.6k
Forks
815
PR merge metrics
No merged PRs in 30d

Description

I was trying to use the reference section of the documentation to learn how to use floats, and I found numerous missing functions. As a brief example, from containers.py:

_Split:
is_modal
get_key_bindings
get_children

HSplit;
preferred_width
preferred_height
reset

VSplit:
preferred_width
preferred_height
reset

FloatContainer:
reset
preferred_width
write_to_screen
_draw_float
is_modal
get_key_bindings
get_children

Float:
get_width
get_height
__repr__

WindowRenderInfo
visible_line_to_input_line

ScrollOffsets:
top
bottom
left
right

Window:
reset
_write_to_screen_at_index
copy
_apply_style

Etc.

Some of these may be private or functionally equivalent to parent functions, but in those cases the docs should link to the parent functions, or at the very least link to the intended parent object, which currently isn't the case. Some of the above undocumented functions are also unique to the classes.

Trying to learn how to use a library when the reference docs can't be trusted to be complete is very frustrating. Specifically I wanted to know how to hide floats or dialogs, and I didn't know if a hide() function was missing because the docs are incomplete or because the function doesn't exist. It basically means I have to rely on examples and Google instead of what should be the most trustworthy source for information.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Compare the documentation reference for containers.py with the listed methods on _Split, HSplit, VSplit, FloatContainer, Float, WindowRenderInfo, ScrollOffsets, and Window. Determine which entries are private or inherited, then link them to parent objects or document unique functions; verify that the reference explains whether floats or dialogs can be hidden.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.