Shahriar Heidrich (ddc9a235) at 04 Jun 19:49
Bump version to 0.7.3
Shahriar Heidrich (57e5c328) at 03 Feb 22:39
Fix ls . bug (raised exception on any mark)
... and 1 more commit
Shahriar Heidrich (d6f0ec97) at 03 Feb 21:39
Fix fs-aware mark typing in manager
Shahriar Heidrich (a1046af6) at 04 Jan 20:49
Comment out dependency on fs-reduction-tree-cache
Shahriar Heidrich (f9e134bf) at 24 Dec 00:52
Fix most warnings during doc build
... and 1689 more commits
After thinking about it some more, my vote is for just leaving the docstrings themselves as they are for now by enabling sphinx.ext.napoleon, because maybe good reasons to make them consistent in one direction or the other will come up in the future.
Completely agree with everything else you wrote.
I had a look again as well and what I get is:
Args:) docstrings.:params: (plural!) field list, which I can't find documented anywhere in Sphinx's docs, followed by a standard bulleted list for each param - almost definitely a non-standard way of documenting parameters, although valid ReST.:param parameter_name: docstrings.
:param low_limit: (``int``) -- ....
:param int low_limit: ... or :param low_limit: ... followed by :type low_limit: int.So I guess eventually, a significant fraction of the non-Google-style docstrings should be updated anyway, no matter which style is preferred, which means making them consistent in any direction shouldn't be that different in terms of effort.
But if you guys prefer ReST-style docstrings regardless of the existing ones and would e.g. use this style for a brand new project as well, it still makes sense to update them in that direction, of course.
As far as I can tell, this project's online documentation is meant to be built automatically by ReadTheDocs. But looking at its project page over there, it seems the current version is the one from 4 years ago. And indeed, new additions to the docs like the one from #687 aren't visible in the online docs yet.
Maybe some configuration needs to be updated? Instructions for letting RTD configure the GitLab project on behalf of the user can be found on the How to connect your Read the Docs account to your Git provider page of the RTD docs, but if that doesn't work, it can also be done by manually adding a webhook to the GitLab project.
Not sure if this was the right choice: Most of the docstrings use ReST syntax like :param ...: ..., but at least a handful use Google docstring syntax (Args:).
The Napoleon extension lets Sphinx parse the latter correctly, but maybe it would be better to turn them all into ReST-style docstrings instead for consistency?
I think most people prefer the Google syntax, but making it consistent the other way round by turning all ReST-style docstrings into Google-style ones would be way too much effort.
The docs build currently outputs quite a few warnings. This MR fixes the ones that are easy and sensible (IMO) to fix.
Shahriar Heidrich (7afe42e6) at 15 Dec 00:49
Fix most warnings during doc build
... and 16 more commits
Since this now installs a package named scripts into the Python library dir, maybe it has become more important to point out to people that they should be doing this in a venv (of course that's a good idea in general but now even moreso due to the higher likelihood of a name collision with something else given the generic name).
@smheidrich you inspired this, would you like to sanity check it?
Other than the comments i left, looks good to me
Same here as in the README comment regarding that it should be fine to reduce this to just pip install .[dev].
I think for this repo it wouldn't even have been strictly necessary to replace setup.py with pyproject.toml, but it's probably a good idea anyway