search

spyder-ide / qtpy

Provides an uniform layer to support PyQt5, PySide2, PyQt6, PySide6 with a single codebase
MIT License
987 stars 153 forks source link

Add basic project documentation and example usage #85

Open goanpeca opened 8 years ago

goanpeca commented 8 years ago

Written and edited by @CAM-Gerlach (OP was initially empty):

SylvainCorlay commented 8 years ago

FYI, readthedocs is not very good to deal with dependencies like Qt. But it now supports a conda environment.yml. Check out qtawesome's rtd configuration (readthedocs.yml + environment.yml).

AndydeCleyre commented 7 years ago

Do the docs exist in some format?

machinekoder commented 6 years ago

A simple example in the README would work as well.

dalthviz commented 3 years ago

Related issues:

dalthviz commented 3 years ago

@CAM-Gerlach would you like to work on this?

CAM-Gerlach commented 3 years ago

I can't promise anything like a full-on docs site like we have for spyder-docs or the API docs (at least in the near term), but I was actually already planning to at least update and expand the README and add a contributing/dev guide to address some of these issues (and replied in each of them with more detail).

It looks like the simplest low-hanging fruit item being requested here (beyond the more specific needs identified in the linked issues, which I responded to), was a few examples of using QtPy instead of the specific bindings; I can try to make some up based on what Spyder does, but as I'm nowhere near a Qt expert, @dalthviz if you could point to or outline some common examples that would be really helpful.

Also, as I know there have been questions and requests to clarity the existing API that QtPy generally follows, I'd think we might want to revise this sentence:

Basically, you can write your code as if you were using PySide2 but import Qt modules from qtpy instead of PySide2 (or PyQt5)

to say "as if you were using PyQt5", since as I understand that's the API that QtPy generally follows at present, and also list the Qt6 APIs there, as well as link the Qt and PyQt5 docs. That would then be a jumping-off point for the additions in #61 that explain where QtPy diverges from that documented baseline.

If there's any other low-hanging fruit you would like me to try to do as part of this issue, as opposed to one of the more specific ones or a follow, please do let me know!

CAM-Gerlach commented 3 years ago

As another low-hanging fruit item, the __init__.py contains a substantial amount of general information and examples in its docstring that could be moved to or included in the README to be much more visible, with a bit of cleanup.

dalthviz commented 3 years ago

I think adding some more information in the README is good enough and using the info already in the __init__ could be nice :+1: Thanks @CAM-Gerlach!

Also, at https://github.com/spyder-ide/qtpy/issues/200#issuecomment-544803437 a mention to a documentation page that the Glue project has related to QtPy (in terms of how to use it) could be useful too

CAM-Gerlach commented 3 years ago

Great, that's helpful thanks. I'll compile a master list of the things we want to add in the OP and links thereof, since it doesn't have any content as it is.

CAM-Gerlach commented 3 years ago

Not directly related, but I think it would be a good idea to add back the old PYQT4 and PYSIDE package-level constant, always set to False, for backward compat for code that checks them, and document them here? We did retain the now-obsolete is_old_pyqt and is_pyqt46 variables which were only used internally and not indicated as public module-level constants (ALL_CAPS), so it would make much more sense to include those as well/instead (since external code might be checking for them). I can submit a PR if you agree.

CAM-Gerlach commented 3 years ago

Updated the OP as discussed above

dalthviz commented 3 years ago

Not directly related, but I think it would be a good idea to add back the old PYQT4 and PYSIDE package-level constant, always set to False, for backward compat for code that checks them, and document them here?

Makes sense to me :+1:

CAM-Gerlach commented 3 years ago

Thanks, opened as PR #279