Doc style preference #1029
Description
Activity
- added a commit that references this issue on Sep 24, 2024
Just from the look of things, I don't like Sphinx style--it's too cluttered. I've been leaning towards Google Convention I believe but unsure as I've nvr really put time into learning the full style. I've only used pydocstyle in the past but it supported more than one type. In this project, I haven't put any effort in as there was a lot more code problems to solve first and we have docs. I'm not sure how many people are actually reviewing the api.
I also feel that type declarations in the doc strings are a bit irrelevant now that we have actual type hints implemented, but oh well.
Well since you already solved it for the sphinx stupid, let's just leave that and that will get merged. If I want to change it, I can do that later.
Yeah, I used it as a first pass just because it seemed like the most commonly used within the existing codebase, and threw up some examples there.
A while back, I looked to see if there were any good tools that could convert between the styles, and pyment is one option that came up, though I remember running into some problems in my quick tests. If it works, we could do a big one-off conversion at some point. Doing it by hand would be pretty labor intensive.
Side note: from a quick look, you can see that the existing docs don't actually work totally correctly:
https://python-semantic-release.readthedocs.io/en/latest/api/semantic_release.hvcs.gitlab.html
I think there are plugins that we can enable to make Google docstyle play nice if we switch to it.
I just tried it locally with pyment -w -t -i auto -o google .. It definitely gets the broad strokes, but also seems to have some bugs.
Well that's cool, it would make the job much faster. I did see that error before. I think it's because sphinx wants like each argument on a different line. I'm fine with sphinx format for now, I'll just have to learn it.
🎉 This resolution has been included in version 9.8.9 🎉
The release is available on:
Question
I started looking at fixing some of the sphinx errors, but Ruff and sphinx started fighting over things like
Then I realized that we don't have a standard docstring convention at all (also, in Google convention, at least, it's Args not Arguments, and it's not underlined). Many / most of the docs are in Sphinx style:
While these don't have the explicit type hints that the other docs do, I checked, and Sphinx can infer those anyway, though it's harder to read directly in the code.
Is it safe to assume we want to move towards using Sphinx docs style?
Side note: Looks like ruff currently doesn't support sphinx docstyle