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)