Documentation Overhaul - Githubissues

jldbc / pybaseball

Pull current and historical baseball statistics using Python (Statcast, Baseball Reference, FanGraphs)

MIT License

1.18k stars 323 forks source link

Documentation Overhaul #298

Closed tjburch closed 1 year ago

tjburch commented 1 year ago

Creating an issue to better track the documentation rewrite.

[x] Rewrite README (PR #297)
[x] Update contributing.md to be a contribution guide rather than suggestions (PR #300)
[x] Docstring cleanup. Ultimately if we want to use Autodocs/Napoleon we need google or numpy version. Personally prefer google, but happy to discuss (old issue #125)

If we decide to go to Sphinx/RTD ~~- Migrate docs to rst~~ ~~- Add sphinx as dependency~~

Feel free to comment other necessary things, can add to the list. Also citing #189 since this is somewhat a rehash of that.

tjburch commented 1 year ago

I don't think I'm going to do Sphinx/RTD. If someone else wants to mess with it, it'd be a good add, but I don't have bandwidth for it. Otherwise it might be good to standardize docstrings and then call this good.

erin2722 commented 1 year ago

Hi there @tjburch !

I am a new contributor hoping to start with a useful but easy first issue-- would standardizing all of the docstrings to google style be a helpful first step?

tjburch commented 1 year ago

Hi @erin2722! Thanks for the interest. Theres been some general disagreement about using docstrings in the Discord that never made its way here.

I would say it might be worth a comb over to clear up any confusing/under documented regions of code, or docstrings that look super out of place, but I don't think I would go full google style.

Also if you haven't, check out the discord.

tjburch commented 1 year ago

Closing with the merge of #340. I think we're in a pretty decent spot.