Use Sphinx autodoc for documentation. #443
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Existing API docs were moved into docstrings, and Sphinx's autodoc extension is used to generate the API reference automatically.
Without this, autodoc was adding the close method to all the subclasses of MSSBase that implemented it. It didn't add things like grab and such, since the subclasses didn't implement it. While I'm at it, also make the close method safe to call multiple times.
Contributor
Author
|
I suspect that the errors are about the changes to how close() is handled, but I'll investigate. I can reproduce them here with xvfb-run. |
Owner
|
Nice!
No, that's OK to document only objects that users will encounter. |
First, we previously patched ctypes.WINFUNCTYPE in any time mss.windows was imported, so that autodoc could import mss.windows. Instead, move that to just when we're running Sphinx. Second, when I added _close_impl, I accidentally deleted the super() call in xshmgetimage. This mean that it never closes connections, and exhausts the server's client limit. Finally, in a previous commit, I tested changing mss.lock from a Lock to an RLock while I was dealing with the fact that MSSBase.close holds the lock, and the xlib implementation grabs the global lock. That was not a great solution, so I backed that out. Instead, the xlib implementation just trusts that it's run under the lock. However, a better implementation might be to create a per-object lock in MSSBase to protect _closing, instead of using the course-grained global lock.
BoboTiG
approved these changes
Dec 21, 2025
BoboTiG
reviewed
Dec 21, 2025
This adds extra detail to some docstrings, and brings formatting in line with Sphinx conventions.
Owner
|
Should we merge this, and iterate if needed? |
BoboTiG
reviewed
Dec 21, 2025
Contributor
Author
Yeah, that's what I planned last night... then came across that last batch of doc fixes I added to the PR! Later today, I can incorporate your suggestions, check the doc build, and mark the PR as ready. |
Most constructor parameters weren't being documented by autodoc, since __init__ wasn't documented. If we added the __init__ docstrings to the class documentation (autoclass_source="both"), then that puts an awkward "Initialize a ScreenShot object" or similar sentence in the class constructor documentation in the rendered output. Instead, we put the __init__ parameter docs in the class docstring, and removed __init__ docstrings. Added "See also" sections to make looking up constructor parameters across __init__(**kwargs) chains a little more obvious. Added other requested changes: * Added mss.darwin.IMAGE_OPTIONS to the docs * Added docstring for mss.darwin.MSS.max_displays instance variable * Added docstrings to NamedTuple classes in mss.models * Added formatting for code samples in ScreenShot.bgra and rgb
BoboTiG
reviewed
Dec 22, 2025
Owner
|
Thank you very much @jholveck, that's cleaner now, and properly documented from the code. I love it! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This changes the API documentation generation to use Sphinx autodoc. The existing API docs were moved into docstrings.
There's still cleanups to be done on the documentation, but this seemed like a place to start.
My change does delete some imported classes and constants that were in the API docs for reasons I'm not really clear on, such as mss.darwin.CGPoint and mss.windows.MONITORNUMPROC. Should these still be in the docs?