DOC: Single Document For Code Guidelines

[Stockfoot]

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.

[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.

[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?

[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.

[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?

[moaraccounts]

@Stockfoot I'm new to GitHub, learning first by contributing to documentation. Do you need/want any help?

[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.

[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:

Linting Check for use of not concatenated strings (This is from code_checks.sh) Test Case for bare pytest raises (This whole example would be from validate_unwanted_patterns.py, lines 57-114)

[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

[sahilpatni95]

I am a new in contributor and have never really done this so I have a question that I hope you can answer.

[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?

[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!

[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!

[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.

[Stockfoot]

I haven't submitted anything else because I am stuck with the trailing white space issue and am unsure of how to proceed

[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?

[Stockfoot]

@moaraccounts Fork my "Coding-Style-Guideline-Documentation" branch, make the changes, then do a pull request on that branch

[rajaryanbanka]

I would like to take this up.

[arneja-arnav]

This thread seems inactive. Is it alright if I assign myself to work on this issue?

[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.

[harshvardhan2707]

take

[arneja-arnav]

Take