Skip to content

Improve contributing docs #125

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
2 of 3 tasks
hammer opened this issue Aug 19, 2020 · 8 comments
Closed
2 of 3 tasks

Improve contributing docs #125

hammer opened this issue Aug 19, 2020 · 8 comments
Labels
documentation Improvements or additions to documentation

Comments

@hammer
Copy link
Contributor

hammer commented Aug 19, 2020

A few things missing:

@hammer hammer added the documentation Improvements or additions to documentation label Aug 19, 2020
@hammer
Copy link
Contributor Author

hammer commented Aug 19, 2020

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

@tomwhite
Copy link
Collaborator

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
Copy link
Collaborator

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
Copy link
Contributor Author

hammer commented Sep 3, 2020

@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
Copy link
Contributor Author

hammer commented Sep 3, 2020

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

@hammer
Copy link
Contributor Author

hammer commented Sep 3, 2020

@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
Copy link
Contributor

aktech commented Sep 8, 2020

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
Copy link
Contributor

aktech commented Sep 17, 2020

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

@tomwhite tomwhite closed this as completed Nov 5, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

4 participants