Improve contributing docs

[hammer]

A few things missing:

• information about Mergify Investigate mergify #107
• file an issue before submitting a PR and be sure to mention the issue in the PR comments
• clarify docstring style https://github.com/pystatgen/sgkit/pull/114#issuecomment-676584075

[hammer]

@jerowe @daletovar @timothymillar would love your input on what we need to add/remove/change in our contributing docs.

[tomwhite]

file an issue before submitting a PR and be sure to mention the issue in the PR comments

On https://pystatgen.github.io/sgkit/contributing.html#issues it already says,

Before starting work, make sure there is an issue covering the feature or bug you plan to produce a pull request for.

But it should be changed to say to mention the issue in the PR comments.

[timothymillar]

The docs seem to cover most things without being to long which is great (I should have read up on pre-commit a bit more before #114).

It may be good to have some explicit examples on how and when to include array shape and type information within a docstring.
This can improve clarity of what the function does, especially when using standardised dimensions.
That being said, I would typically just follow the docstrings of related code. So it may not be necessary to explain this in great detail once a standard is enforced.

I also like to look at past accepted PR's and It could be useful to highlight an exemplar PR in the contributing guide.

[hammer]

@jeromekelleher mentioned in the last developer call that he had a guide from another project that could be useful to link from our documentation.

There's also been some discussion in #129 and #140 on the use of branches in developer forks and how to keep those branches up to date. Do we need to add some text to our contributing docs to reflect the consensus from those issues?

[hammer]

Also I believe https://github.com/pystatgen/sgkit/issues/216 addresses the docstring style task above.

[hammer]

@tomwhite do we need to augment the contributing docs to ensure we don't miss functions when building the Sphinx docs as in https://github.com/pystatgen/sgkit/issues/212?

[aktech]

I see #212 is closed, but I still don't see stats and io modules docs, is that intentional?

do we need to augment the contributing docs to ensure we don't miss functions when building the Sphinx docs as in #212?

The instructions for the same does seems to be fixing here: https://pystatgen.github.io/sgkit/contributing.html#docstrings

Also I believe #216 addresses the docstring style task above.

I have made a comment here on my understanding of the same: https://github.com/pystatgen/sgkit/issues/216#issuecomment-688964428

Let me know, if these makes sense, I will open a PR for the same.

[aktech]

@tomwhite @hammer Can this be closed now? as #261 is merged