Add basic project documentation and example usage

[goanpeca]

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

• Add/move general information currently contained in __init__ docstring to the README for visibility
• Clarify that QtPy follows PyQt5 conventions, and link Qt and PyQt5 API docs
• Add examples of using QtPy in place of the specific bindings
• List/describe the methods/helpers specific to QtPy (listed in Add documentation for methods or helpers that are specific to qtpy #61 )
  • from qtpy.QtCore import Signal, Slot
  • QFileDialog helpers
  • qtpy.QtCore.__version__
  • Others?
• Document the QtPy-specific environment variables (FORCE_QT_API, etc)
• Describe the main package-level constants (PYQT5, PYSIDE2, etc)
• Clarify the benefits of using QtPy with regard to cross-Qt-version migration, and link success stories (described in Add to the readme the importance of qtpy when migrating an application #62 )
  • Modernization: Python 3 and Qt5 git-cola/git-cola#232
  • Glue
• Clarify Qt version compatibility in the readme

[SylvainCorlay]

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]

Do the docs exist in some format?

[machinekoder]

A simple example in the README would work as well.

[dalthviz]

Related issues:

• Add documentation for methods or helpers that are specific to qtpy #61
• Add to the readme the importance of qtpy when migrating an application #62
• Add documentation for how to run tests #66

[dalthviz]

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

[CAM-Gerlach]

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]

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]

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

Also, at #200 (comment) 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]

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]

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]

Updated the OP as discussed above

[dalthviz]

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 👍

[CAM-Gerlach]

Thanks, opened as PR #279