DOC: use shared_docs for isna/notna & isnull/notnull

[jreback]

#16972

also some templates so that we can have distinctive doc-strings that use isnull in the doc-string for isnull (rather than isna), same for notnull.

[yadunathg]

Hi @jreback, I am a beginner here and want to work on this issue but am not able to find documentation of how to use shared_docs. Can you provide an example where shared_docs have been used?

[gfyoung]

@yadunathg : Awesome that you want to work on this? There is no documentation about how to use this, since it is an internal tool, but you can find an example here:

pandas/pandas/core/series.py

Line 82 in 7bef6d8

_shared_doc_kwargs = dict(

You can also search for _shared_docs in the GitHub search bar to find further examples in the pandas codebase.

[lermana]

I don't know if this is the best place to leave this comment, and apologies if I should put this elsewhere. Wanted to bring attention to the fact that the docs. claim MultiIndex.isnull is implemented despite the fact that MultiIndex.isnull appears to be, for all intents and purposes, not implemented.

[gfyoung]

isnull is in fact implementd for MultiIndex (you can check yourself). However, isna is not. I think that should be fixed though @jreback ?

[lermana]

@gfyoung thanks for the reply. well yes there is a isnull method for MultiIndex but it calls pandas/core/dtypes/missing._isna_new, which does not appear to be implemented for MultiIndex?

[gfyoung]

@lermana : Ah, yes, that's true. Then we should decide whether to implement it (long-term) or just patch the docs immediately. I think we should aim for the former if possible.

[lermana]

@gfyoung cool! would def. be a neat feature to have.

A related question: for both isnull and duplicated DataFrame methods, is there a reason why the docs. don't specify that the functions don't actually look at the DF index / provide a link to the analogous Index functions?

Happy to submit a PR for the docs. updates if that would be helpful. Just something I was curious about, don't know if it's mentioned elsewhere in the API specification and missed it... this may not be the proper place for this thread.

[gfyoung]

Not AFAICT. Go for it then!

[lermana]

Cool, will do!

[yihuajack]

The consequence of using _shared_docs is that the See also section of the references to isnull and notnull are not informative. For example, the See also section of isnull is

See Also
--------
DataFrame.isnull : Alias of isna.
DataFrame.notna : Boolean inverse of isna.
DataFrame.dropna : Omit axes labels with missing values.
isna : Top-level isna.

which is exactly the same as the See also section of isna. However, the following seems better:

See Also
--------
DataFrame.isna : Detect missing values.
DataFrame.notnull : Boolean inverse of isnull.
DataFrame.dropna : Omit axes labels with missing values.
isnull : Top-level isnull.

This issue is also mentioned in #27609.