Clarify documentation on how to use "status_bar", as part of a TerminalMenu instance

[mvincerx]

While the default style mentions status_bar as having similar behavior to the title element, there's no example of how to include it, what datatype it is (says it's a string, but it's apparently not), or how it might be used as a "callable".

Consider adding more detail to A more advanced example:

I tried following the README documentation, but the proposed solution below for "status_bar" fails--and there's no help. When describing each property of an instance or class it is advised to describe its implementation, datatype, and expected behavior independently, not as a comparison to another property ("title can be a simple string [ ...] The same applies to the status_bar...") because this approach can overlook subtle behavioral differences.

[...]
def main():
    main_menu_title = "  Main Menu\n"
    main_menu_status_bar = "Message" (???)
[...]

    main_menu = TerminalMenu(
        menu_entries=main_menu_items,
        title=main_menu_title,
        status_bar= main_menu_status_bar (???)

I would like to simply have a status bar at the bottom of the main menu.

[IngoMeyer441]

Hey @mvincerx, thanks for trying my library. :+1: So the status_bar parameter is not working for you at all? I used your example:

#!/usr/bin/env python3

from simple_term_menu import TerminalMenu


def main():
    main_menu_title = "  Main Menu\n"
    main_menu_status_bar = "Message"

    main_menu_items = ["a", "b", "c"]

    main_menu = TerminalMenu(
        menu_entries=main_menu_items,
        title=main_menu_title,
        status_bar=main_menu_status_bar,
    )

    main_menu.show()


if __name__ == "__main__":
    main()

and I get

The status_bar parameter should act like the title attribute with the only difference that is also takes any callable object. Therefore, I described the status bar in comparison to the title bar. But sometimes it is a bit difficult (for me) to write documentation from the user's perspective. I am always grateful for improvements to this project.

[mvincerx]

@IngoMeyer441 Thanks for your reply. I'm now including the version of simple-term-menu that I use:

simple-term-menu (0.10.5)

Can you confirm? Is the status_bar functional for the above version? Or can you tell me in which version was the status_bar introduced?

[mvincerx]

I receive a "TypeError" as shown below. I'm using your example from above.

I'm using Python 3.6.9.

Can you help?

[mvincerx]

Confirmed as a version error. I upgraded to simple-term-menu==1.2.1

Now, the status_bar works. And yet, new requirements dictate format of new properties on the TerminalMenu object.

I still feel much improvement is needed for documentation. I appreciate the work you've done for this library. Its simplicity is part of what attracted me. :)

[IngoMeyer441]

Do you have an example of another documentation which is better? I already thought about creating a multi page documentation (for example on read the docs) with an API reference which would include datatypes and independent descriptions. But it also a matter of time...

[mvincerx]

Following are a couple of examples.

• https://docs.01.org/clearlinux/latest/ (I worked a lot on this project)
• https://docs.readthedocs.io/en/stable/api/index.html (ReadTheDocs API)

I highly recommend using Read the Docs (RTD), with Sphinx. Consider launching an MVP site first; then later you could add the full API. The latter is the most challenging. Sphinx is an ideal fit for your docs because almost everything is written in Python. I'm willing to help a bit if you decide you want to launch a docs site.