Location of the documentation
https://pandas.pydata.org/docs/development/code_style.html https://pandas.pydata.org/pandas-docs/stable/development/contributing.html#code-standards
Documentation problem
Most of the documentation for the coding style guidelines is limited and in multiple locations. Much of the coding style is in a script.
Suggested fix for documentation
I propose to create a single document that contains all the coding guidelines. This will allow new contributors to easily see all the required syntax and style for the project. This also allows newer users to not have to guess against a script or have to keep submitting code over and over to find mistakes.
Comment From: simonjayhawkins
I propose to create a single document that contains all the coding guidelines.
perhaps the google style could be a good template or basis for outline http://google.github.io/styleguide/pyguide.html
personally i prefer a well structured reference style document to a informal prose on the subject.
I think that the reason we have the two documents is that the contributing guidelines contains the descriptive introduction for first time contributors and the code style document contains more details. This second document was only recently introduced and adding the content and some migration of content from the contributing guidlines is WIP.
contributions and PRs welcome.
Comment From: Stockfoot
I agree that the google style is a good template. I am currently in an Open Source course and would like to contribute to this.
I am a first time contributor and have never really done this so I have a question that I hope you can answer.
Is it useful/okay practice if I get the outline of the document and the information that already exists about the code style into the document or do I need to try and have a complete document for a pull request?
Comment From: simonjayhawkins
Is it useful/okay practice if I get the outline of the document and the information that already exists about the code style into the document or do I need to try and have a complete document for a pull request?
smaller more atomic PRs are easier to review and will likely get approved/merged quicker.
Ok to start small, any incremental improvements welcome., but probably better to not have a document with empty sections. so could use the google doc for inspiration but not actually have a document with an outline and missing content.
Comment From: Stockfoot
@simonjayhawkins I have begun writing the document in markdown and saw in the documentation section that the project uses Sphinx. Should I switch over to Sphinx before proceeding further or is markdown okay?
Comment From: moaraccounts
@Stockfoot I'm new to GitHub, learning first by contributing to documentation. Do you need/want any help?
Comment From: Stockfoot
@moaraccounts sure that would be good. Like I said I have a markdown file going but I'm not sure if I need to switch to Sphinx. I have pulled the coding guidelines from various places that was already presented. I think the next step is I need to pull unique requirements from the style script but I am not sure how to do that.
Comment From: moaraccounts
@Stockfoot I've been looking at the script, trying to understand the requirements. What if you created the documentation in a similar manner to how the code_checks script is constructed? Like, have one section on Linting and pull in the different messages from the other scripts as subsections? Is that what you mean by pulling the requirements from the style script?
For example:
Comment From: Stockfoot
@moaraccounts Yeah that is what I am getting at. Basically a style guide that would allow a first time user to read it and understand the formatting and requirements for how they should code, The script would act as a backup instead of a newer user having to submit over and over to see where they are formatting things wrong. pandas Coding Style Guide example.pdf Here is the markdown file I have going, I am trying to format it kind of like the python style guide
Comment From: sahilpatni95
I am a new in contributor and have never really done this so I have a question that I hope you can answer.
Comment From: moaraccounts
@moaraccounts Yeah that is what I am getting at. Basically a style guide that would allow a first time user to read it and understand the formatting and requirements for how they should code, The script would act as a backup instead of a newer user having to submit over and over to see where they are formatting things wrong.
Awesome. I like the .pdf you have going. And I think you're fine using markdown (see this), but good to take a look at this link which points to the reStructuredText Primer just in case. Is there anything I can help with?
Comment From: Stockfoot
@moaraccounts Thanks for the links! I will work on this some more this week and try submitting a pull request. If it gets accepted then it opens the door for everyone else to easily contribute to the document!
Comment From: Stockfoot
@simonjayhawkins @moaraccounts I tried submitting a pull request for the .rst document but it failed. It is saying there is trailing white spaces after every single line on the CI/Check but when I pull it up in my editing program there are no trailing white spaces. I'm sure it is something simple but perhaps you can shed some light on what is happening. Thanks!
Comment From: moaraccounts
@Stockfoot @simonjayhawkins I pulled Stockfoot's branch, compiled the docs and ran code_checks.sh. I'm seeing the trailing whitespace errors. However, not sure how to address it. I'm not using an IDE, just Terminal. Hmm. Actually, I'll try pull up the docs in Sublime Text or something and see if that gives me more info.
Comment From: Stockfoot
I haven't submitted anything else because I am stuck with the trailing white space issue and am unsure of how to proceed
Comment From: moaraccounts
@Stockfoot I hear that. I'm looking up ways to remove trailing whitespaces from .rst files. But I don't know how to push my changes back to your branch, ha. N00b to that. Any advice?
Comment From: Stockfoot
@moaraccounts Fork my "Coding-Style-Guideline-Documentation" branch, make the changes, then do a pull request on that branch
Comment From: rajaryanbanka
I would like to take this up.
Comment From: arneja-arnav
This thread seems inactive. Is it alright if I assign myself to work on this issue?
Comment From: moaraccounts
Certainly!
On Feb 16, 2022, at 8:43 AM, Arnavdeep Singh Arneja @.***> wrote:
This thread seems inactive. Is it alright if I assign myself to work on this issue?
— Reply to this email directly, view it on GitHub, or unsubscribe. Triage notifications on the go with GitHub Mobile for iOS or Android. You are receiving this because you were mentioned.
Comment From: harshvardhan2707
take
Comment From: arneja-arnav
Take