[BUG] Documents at https://ptg.bczsalba.com/pytermgui.html seem broken or outdated

[jima80525]

Describe the bug I'm trying to walk through the example given here: https://ptg.bczsalba.com/pytermgui.html#combining-our-knowledge-to-create-an-application (and in earlier examples) and they all seem to have odd errors in them.

For example, the first sample code listed has:

import pytermgui as ptg

with ptg.WindowManager() as manager:
    window = ptg.Window(
        "[wm-title]My first window!",
        "",
        ["Exit", lambda *_: manager.exit()],
    )

    manager.add(window)
    manager.run()

Hitting the "Exit" button when running this app throws an exception as there is no 'exit()method on theWindowManager` class. This is fairly easy to fix, but the later example (at the link above) doesn't work in non-obvious ways.

To Reproduce Steps to reproduce the behavior: using pytermgui 5.0.0 on linux in a RoxTerm window. Run the above program. Click on the "exit" button

Expected behavior Program should exit cleanly for the exit() case. The example code should run in the namespace.yaml case.

System information pytermgui 5.0.0 Ubuntu 20.04 Roxterm 3.12.1 (just tested in "Terminal" which ships with Ubuntu 20.04 - same results)

Add the output of "ptg --version" in this box.

pyTermTk on  main [?] via 🐍 pyenv 3.10.4:pytermtk took 2s ➜ pip freeze
pytermgui==5.0.0
PyYAML==6.0
pyTermTk on  main [?] via 🐍 pyenv 3.10.4:pytermtk ➜ ptg --version
^[[4;1320;940tfatal: Needed a single revision
PyTermGUI v5.0.0

Python: 3.10.4
Platform: Linux-5.13.0-40-generic-x86_64-with-glibc2.31
pyTermTk on  main [?] via 🐍 pyenv 3.10.4:pytermtk ➜ 1320;940t

Note that there is a "fatal" line in the output and that it leaves the terminal with garbage characters.

Possible cause

Possible solution

Seems like some of the documents are out of date, but there also seems to be a different problem.

[bczsalba]

Hey there!

The exit part of the docs is completely valid, that method was removed with 5.0.0 as it was no longer necessary (stop did the same thing already). I will get onto fixing that.

Which non-obvious errors come up in the second example? To be quite honest it was written around the time of 1.0.0, so some things are a bit off on it from what I can see, namely the button being keyboard-actionable but not being visible or clickable, and the height of the window not being correct on launch. The button issue I'm uncertain about, but the window height is probably to an extent related to it. I suspect that the introduction of Container.overflow broke some things here unfortunately, and I haven't gone back to check.

With the next release being based around layouts, I suspect that this page will soon be rewritten anyways, though there may be a time-delay on the documentation as I'm a bit busy with university work. Will try fixing as soon as possible.

Thank you for the report, and interest in the library!

[jima80525]

Thanks for the follow up!

The more detailed example I stopped working on after two attempts. First issue was this line:

namespace = ptg.YamlLoader().load(PTG_NAMESPACE)

where PTG_NAMESPACE is undefined. I replaced it with "namespace.yaml", but that's not right. Finally I figured out that this needed the yaml file read into a string. (and to have pyyaml installed). Once I did that, it was close - the vertical layout (as you mention above) is a little messed up with the inner two boxes losing their lower edges to the outer box.

I totally get the position you're in if you're about to release a major overhaul to how this works. It definitely makes sense to get that work done first and then update the docs (AND make sure you stay on top of your studies - that's way more important!).

Just wanted to make sure I passed on the info. Thanks for the work you put into this tool and good luck!

[bczsalba]

Yup, no idea where PTG_NAMESPACE came from. Thank you for letting me know about the issue, I'll close this thread when the docs have been "modernized".

[leftbones]

Just wanted to chime in that it does seem like the docs need a bit of an overhaul. I almost wonder if they would be better moved to this repo, perhaps in a docs folder or the wiki, just so they could be better maintained by users as well.

[jeffwright13]

I am interested in seeing improvements in the docs as well - they are pretty comprehensive as far as annotating the API goes, but I don't really feel like there's a graduated "start here, then progress" path. There is a rudimentary program to show the basic window, but nothing much beyond that, at least that I could find. I dunno, maybe I am slow, but I'd love to see some kind of increasingly more complex series of tutorials.

[leftbones]

Yes I definitely want to stress that the docs, in terms of quality, are amazing. The pictures, descriptions, all on point. The main issue is that they are outdated, which is bound to happen when a project like this is still in the breaking changes phase.

[bczsalba]

I very much agree with all the points made above! The API docs are pretty much 100% up to date, as they are generated straight from the source, but the manually written markdown docs have been neglected a bit (well, last I really updated them was around 1.0.0, so maybe more than a bit). My biggest problem with documenting is that I, as the person who wrote 95% of the library, know my way around it to an uncomfortable level, where I can usually solve temporary limitations/bugs by exploiting some "hack" around the system. Because of this, I'm not quite sure which parts should be explained more thoroughly, and what is particularly hard to get around.

I would generally love to hear some feedback on that part specifically. I have a lot of local files I use for testing/"sandboxing", but most of them are tiny and not really useful for much. I would also be open to seeing some community made examples, as you guys probably know the things discussed above better than I do.

It's worth mentioning that the current documentation generator will probably be replaced at some point with something I'm planning to write. Essentially, it would be a wrapper around ptg.inspect, which would use that function to document any module and generate html from it. This is still mostly in the planning/early architecture change, so no idea when (if ever) it will become a thing. Part of the reason I want to make this is that the current system isn't really build around creating static markdown based documentation, which would be really beneficial.

TL;DR: I'd love to hear input on which parts of the library need examples/documentation, since I'm not really able to determine the complexity of the systems I know completely, and if you are interested, I would love to accept some PRs that add relevant examples to the project. Better documentation is on the way, but with an uncertain timeline

P.S.: Thank you for appreciating the documentation :) I spent a lot more time on it than I think is visible, so it's great to hear that it was worth it!

[jeffwright13]

For me, I am having a hard time just getting off the ground. What I'd like to have is a boilerplate file that provides me with a blank window/frame/whatever-the-terminology-is-here that I can start dropping widgets into. I can probably figure out all the stuff to put in there once I have a basic sandbox.

For my immediate needs I'd like to drop in a label that displays a single line of ANSI-coded text; below that, some buttons, all on the same row (kind of like a tabbed/notebook widget), and that accept clicks and call other code based on those clicks; another row that is basically a scroll-view widget, which has the ability to show either more ANSI-coded text, or a tree-like widget that itself is clickable and then shows more ANSI coded text. :-) I'd also like to have some keybindings that let me quit, and possibly navigate around the whole thing with the arrow keys.

As you have probably guessed by now, I want to replicate this: https://github.com/jeffwright13/pytest-tui

[jeffwright13]

I would not be opposed to pitching in to develop some graded tutorials either.

[bczsalba]

So I've added both a simple boilerplate application:

And a simple (and very yellow, for some reason) implementation of said boilerplate app:

To the repo. Thank you for the suggestions!

[jeffwright13]

Amazing, thank you so much! I have some studying to do. :-)

[jeffwright13]

BTW the provided code in boilerplate.py still calls exit(), instead of stop(), resulting in the error originally reported in this thread.

[bczsalba]

BTW the provided code in boilerplate.py still calls exit(), instead of stop(), resulting in the error originally reported in this thread.

Old habits die hard, or whatever they say now. Fixed!

[bczsalba]

A tiny update on this; I've been working on completely rewriting the docs in MkDocs Material, using markdown-generated SVG screenshots and such. It will get more focus once the new TIM engine is shipped, but most of that area of the library is already documented there.

[bczsalba]

Forgot to close this, but the new docs have been up for a while now and they should fix all of these issues. Thanks for the shout!