-
-
Notifications
You must be signed in to change notification settings - Fork 106
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
API documentation of filelock.FileLock
is inaccurate
#132
Comments
True.
I'd argue that should contain the platform-specific documentation and not the generic one. Only the documentation is where I'd expect it differently.
I'm happy with the state of things during runtime, the only place where an improvement would be nice is the documentation, so any change should only touch the Sphinx documentation generation. I'm open to people opening such PRs. |
The API documentation of
filelock.FileLock
simply reads:Naturally, this is only true on platforms supporting
fcntl.flock
, else it might be aWindowsFileLock
orSoftFileLock
. I assume that ReadTheDocs runs and produces the HTML pages on a Linux system.I would expect the docs to instead indicate that this is an alias for the lock implementation specific to the platform the code is being run on, which may be any of the three classes. Ideally, this would be true also for
filelock.FileLock.__doc__
at runtime (e.g. forhelp()
in the REPL).I'm not very familiar with Sphinx, so I don't know what the best approach for this is. My intuitive attempt would be to make
FileLock
a subclass of the relevant implementation (i.e.class FileLock(_FileLock)
insrc/filelock/__init__.py
) and give it its own docstring. However, the 'Bases' line in the Sphinx-generated docs would still have to be fixed or suppressed for this particular class.The text was updated successfully, but these errors were encountered: