search

mhammond / pywin32

Python for Windows (pywin32) Extensions
5.06k stars 799 forks source link

No documentation of top-level package/module hierarchy #1535

Open alexchandel opened 4 years ago

alexchandel commented 4 years ago

This project produces a dizzying panoply of top-level modules, including win32, win32com, pythoncom, and pywintypes, but does not provide any overview of them. There is no documentation of the top-level hierarchy at all.

The README is silent. The PyPI page is barren. Calling help(pythoncom) literally crashes python. This website makes no effort to distinguish submodules (like win32com's propsys) from top-level modules (like pythoncom), and provides no location for some types (like com_error).

Should com_error be imported from pywintypes or pythoncom? It doesn't say. Why are pythoncom and win32com separate packages? It doesn't say, and asking crashes python.

Please clearly explain the package hierarchy, and the intended locations from which to import types.

JDLH commented 4 years ago

I recently discovered Pywin32. I would like to learn more about it. The first thing I looked for was some mention in readme.md of where to find documentation. I don't see it, and I think this absence is a problem.

I understand that there is some documentation in PyWin32.chm, and maybe other .CHM files, in the installed module. That's helpful. The readme.md should say this, and explain how to read those files.

Workarounds: Other projects have apparently taken on providing documentation for pywin32.

If the pywin32 project wants to rely on external documentation like these, that is OK, but it should link to them in a discoverable way.

Would a patch adding some of this information to readme.md be welcomed by the maintainers? I don't have Windows, so there's a limit to how well I can describe PyWin32.chm. I can, however, add a section to the readme.

mhammond commented 4 years ago

Yes, I'd absolutely take PRs to improve the docs.

mhammond commented 4 years ago

(It's worth keeping in mind that README.md isn't installed - so changes there are going to help people landing here on github, but not help people once it's installed. The .chm has a shortcut added when the .exe installers are used, so it's relatively obvious to users once it has been installed.

vsalvino commented 4 years ago

@mhammond I know sphinx pretty well (which can be used to produce HTML, CHM, and many other help formats) and would be happy to help move the current docs over to sphinx. If you could provide a little primer on how to build the current help, where the files are located, etc. that would be a great starting point!

mhammond commented 4 years ago

Great, thanks!

https://github.com/mhammond/pywin32/tree/master/AutoDuck is where all the magic happens. The biggest issue is likely to be the format of the markup used in the source files (eg, look for things like @pymethod in almost any .cpp file in the repo)

PeterJCLaw commented 4 years ago

It's worth keeping in mind that README.md isn't installed - so changes there are going to help people landing here on github, but not help people once it's installed.

Would you be open to a PR which added the README to the package? PyPI supports markdown now, so the same document could also be used as the overview on PyPI.

mhammond commented 4 years ago

Sure

Avasam commented 8 months ago

Whilst first-party docs can (and should) definitely be improved, in the interim typeshed does an awesome job at listing top-level modules, packages and aliases:

Relates to #1992