API documentation of filelock.FileLock is inaccurate

[JustAnotherArchivist]

The API documentation of filelock.FileLock simply reads:

alias of filelock._unix.UnixFileLock

Naturally, this is only true on platforms supporting fcntl.flock, else it might be a WindowsFileLock or SoftFileLock. 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. for help() 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) in src/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.

[gaborbernat]

I assume that ReadTheDocs runs and produces the HTML pages on a Linux system.

True.

Ideally, this would be true also for filelock.FileLock.__doc__ at runtime

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 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) in src/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.

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.