DOC: update pandas/core/ops.py docstring with examples for pandas.DataFrame.gt and .ge methods

[ParfaitG]

Checklist for the pandas documentation sprint:

• PR title is "DOC: update the docstring"
• The validation script passes: scripts/validate_docstrings.py <your-function-or-method>
• The PEP8 style check passes: git diff upstream/master -u -- "*.py" | flake8 --diff
• The html version looks good: python doc/make.py --single <your-function-or-method>
• It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

################################################################################
####################### Docstring (pandas.DataFrame.gt)  #######################
################################################################################

Wrapper for flexible comparison methods gt

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
	Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
	Summary does not end with dot
	No extended summary found
	Errors in parameters section
		Parameters {'axis', 'level', 'other'} not documented
	No returns section found
	See Also section not found
	No examples section found

################################################################################
####################### Docstring (pandas.DataFrame.ge)  #######################
################################################################################

Wrapper for flexible comparison methods ge

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
	Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
	Summary does not end with dot
	No extended summary found
	Errors in parameters section
		Parameters {'level', 'other', 'axis'} not documented
	No returns section found
	See Also section not found
	No examples section found

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.

Comparison methods in ops.py including .gt() and .ge() do not have standard docstring like other methods. They use a generalized wrapper summary line. This pull request simply adds examples in line with recent merge for .add() method: https://github.com/pandas-dev/pandas/pull/20246/files

[WillAyd]

lgtm

[TomAugspurger]

Hmm should I be seeing the examples in the docstring?

In [4]: pd.DataFrame.ge?
Signature: pd.DataFrame.ge(self, other, axis='columns', level=None)
Docstring: Wrapper for flexible comparison methods ge
File:      ~/sandbox/pandas-ip/pandas/pandas/core/ops.py
Type:      function

[ParfaitG]

@TomAugspurger ... I followed the recent merged PR link above (same pandas sprint team). However, it seems those df_examples work only in the Arithmetic Operators and not Comparison Operators where its docstring string formats df_examples. Can you see new examples with .add method in your sandbox?

I am thinking we need to adjust the @Appender string conditionally by the operator, op_name, from _op_descriptions dictionary and then format string with df_examples (if not None).

@Appender('Wrapper for flexible comparison methods {name}'
          .format(name=op_name))

Will update PR accordingly.

[TomAugspurger]

Yes, they show up for add. Let us know if you need help progressing on this.