DOC: Code style documentation

[ShaharNaveh]

• ref (comment)
• tests added / passed
• passes black pandas
• passes git diff upstream/master -u -- "*.py" | flake8 --diff
• whatsnew entry

This still needs a lot more work.
I will appreciate any advice/idea/fix.

[ShaharNaveh]

I need help linking the new file here.

[datapythonista]

Don't remember the exact syntax, but you have plenty of examples of links to labels in the docs.

[ShaharNaveh]

Really not sure.

[WillAyd]

You can just name this contributing_code_guide and use that as the target in contributing.rst To address your question above as well

[WillAyd]

You can just name this contributing_code_guide and use that as the target in contributing.rst To address your question above as well

[datapythonista]

@MomIsBestFriend if you can address the comments and leave this ready to get merged please.

[datapythonista]

I don't think this is true. In some cases it makes more sense to represent the object as a string, and in some as its representation. See:

>>> f'today is {my_date}'
'today is 2020-01-01'
>>> f'the object {my_date!r} is not a string'
'the object datetime.date(2020, 1, 1) is not a string'

Better avoid saying when to use the representation, since this is more common sense, and focus on the formatting.

@jbrockmendel do we really prefer {repr(foo)} to {foo!r}. I think I've seen some discussion about this, but not sure this is really an standard we follow, and why the former should be preferred.

[datapythonista]

Where are you getting this standards from? I don't see any of this in the wiki https://github.com/pandas-dev/pandas/wiki/Code-Style-and-Conventions, and I don't think this is an agreed practice, I usually use foo.__class__.__name__.

[ShaharNaveh]

#29775 (comment)

[datapythonista]

Don't remember the exact syntax, but you have plenty of examples of links to labels in the docs.

[datapythonista]

Thanks @MomIsBestFriend can you make this a non-Draft PR please?

@jbrockmendel can you have a look please?

[datapythonista]

I think all these examples are too complicated to illustrate the point here.

You can simply show something like:

foo = 'bar'
type(foo)  # good
foo.__class__  # bad

I think creating classes, too many cases... creates noise, more than help understand the point.

[datapythonista]

Thanks @MomIsBestFriend

@WillAyd can you have a look and see if your comments were addressed please?

[datapythonista]

@MomIsBestFriend can you have a look at the CI please? Seems some things are failing.

[jbrockmendel]

 Linting code-blocks in .rst documentation
##[error]doc/source/development/contributing_code_guide.rst:59:10:F821:undefined name 'new_function_name'
##[error]doc/source/development/contributing_code_guide.rst:59:21:F821:undefined name 'old_function_name'
##[error]doc/source/development/contributing_code_guide.rst:69:10:F821:undefined name 'new_function_name'
##[error]doc/source/development/contributing_code_guide.rst:69:21:F821:undefined name 'old_function_name'

[ShaharNaveh]

I have no idea how to solve it

https://github.com/pandas-dev/pandas/commit/02c0ab52d13dc00623bdf58a08bc51bc5818a2a1/checks?check_suite_id=379658620#step:6:2335

[datapythonista]

I have no idea how to solve it

You can add the new page to this index. So, it's visible, and the error should also disappear.

[datapythonista]

Sorry, I see I forgot to copy the link. Another option is to add the document to this index, instead of creating a new one: https://github.com/pandas-dev/pandas/blob/master/doc/source/development/index.rst

[ShaharNaveh]

Sorry, I see I forgot to copy the link. Another option is to add the document to this index, instead of creating a new one: https://github.com/pandas-dev/pandas/blob/master/doc/source/development/index.rst

This is your preferred way?

[datapythonista]

Up to you, but I think it'd make the page more visible if it's in that index.

[ShaharNaveh]

Up to you, but I think it'd make the page more visible if it's in that index.

Since you suggested it, I will go with that.

Do I just put contributing_code_guide under developer for example?

(and remove the doctree in contributing.rst?)

[datapythonista]

Yep, just have your page as one more item in the list, not sure what's the best position, up to you.

You can probably leave a regular link in contributing, I guess you added an index because of the error

[ShaharNaveh]

I'm considering changing the file name to style or something like that, to make it one word, instead of three.

[ShaharNaveh]

I guess you added an index because of the error

Correct.

[ShaharNaveh]

I hope I did it correct.

[datapythonista]

I'm considering changing the file name to style or something like that, to make it one word, instead of three.

I think style may be a bit ambiguous with other parts of the docs. But renaming to code_style sounds like a great idea.

[datapythonista]

lgtm, thanks @MomIsBestFriend

[datapythonista]

@WillAyd can you have a look please? This should be ready

[WillAyd]

Thanks @momisbestfriend