DOC: added examples to DataFrame.std

[ruankie]

xref #44162

• Added two examples to the documentation of DataFrame.std function so that users can understand how to use it with different delta degrees of freedom.
• Add examples to the documentation of DataFrame.var function

---

• tests added / passed
• All pre-commit linting tests pass

[ruankie]

Apologies for the typo. Here is what I meant:

Closes one part of the two-part issue #44162.

This is an update on the pull-request #44167 that fixes some linting problems using pre-commit.

[MarcoGorelli]

Thanks @ruankie

Content looks good, you just need to fix up linting, see https://pandas.pydata.org/docs/development/contributing_documentation.html#updating-a-pandas-docstring

Can you address #44167 (comment) please?

[ruankie]

@MarcoGorelli
Apologies, I am quite new to this. I just made the update. Hope it works now.

[MarcoGorelli]

@MarcoGorelli Apologies, I am quite new to this. I just made the update. Hope it works now.

Cool, thanks!

Can you also try building the docs for these methods and posting a screenshot? e.g.

cd doc
python make.py clean
python make.py --single pandas.DataFrame.std

[ruankie]

Thanks, @MarcoGorelli.

I am having trouble building the docs locally. I have tried creating a development environment using Docker. However, when I run python make.py clean I get the following error (inside Docker environment) and I can't seem to figure out how to solve it:

(base) root@7e50b674c38b:/home/pandas-ruankie/doc# python make.py clean
Traceback (most recent call last):
  File "make.py", line 377, in <module>
    sys.exit(main())
  File "make.py", line 359, in main
    globals()["pandas"] = importlib.import_module("pandas")
  File "/opt/conda/lib/python3.8/importlib/__init__.py", line 127, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1014, in _gcd_import
  File "<frozen importlib._bootstrap>", line 991, in _find_and_load
  File "<frozen importlib._bootstrap>", line 975, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 671, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 843, in exec_module
  File "<frozen importlib._bootstrap>", line 219, in _call_with_frames_removed
  File "/home/pandas-ruankie/pandas/__init__.py", line 22, in <module>
    from pandas.compat import is_numpy_dev as _is_numpy_dev
  File "/home/pandas-ruankie/pandas/compat/__init__.py", line 15, in <module>
    from pandas.compat.numpy import (
  File "/home/pandas-ruankie/pandas/compat/numpy/__init__.py", line 7, in <module>
    from pandas.util.version import Version
  File "/home/pandas-ruankie/pandas/util/__init__.py", line 1, in <module>
    from pandas.util._decorators import (  # noqa
  File "/home/pandas-ruankie/pandas/util/_decorators.py", line 14, in <module>
    from pandas._libs.properties import cache_readonly  # noqa
  File "/home/pandas-ruankie/pandas/_libs/__init__.py", line 13, in <module>
    from pandas._libs.interval import Interval
ModuleNotFoundError: No module named 'pandas._libs.interval'

[MarcoGorelli]

you need to rebuild the C extensions

python setup.py build_ext -j 4

[ruankie]

Great, it worked thanks @MarcoGorelli.

When opening doc/build/html/index.html, I can see some of my changes rendering but without the examples I put in.

The way I included my examples were to add the examples=_std_examples part in the @doc section right above the std function like this:

@doc(
    _num_ddof_doc,
    desc="Return sample standard deviation over requested axis."
    "\n\nNormalized by N-1 by default. This can be changed using the "
    "ddof argument.",
    name1=name1,
    name2=name2,
    axis_descr=axis_descr,
    notes=_std_notes,
    examples=_std_examples,
)
def std(
    self,
    axis=None,
    skipna=True,
    level=None,
    ddof=1,
    numeric_only=None,
    **kwargs,
):

With the _std_examples referenced further down in the file. This is the same way other function docstrings are implemented, so I do not understand why it does not get rendered. Sorry for all the questions, but can you please point me in the right direction?

Thanks.

[MarcoGorelli]

I think you'll want a substitution, if you check other docstrings which do these substitutions there's probably something like %(examples)s in there

[ruankie]

Finally managed to successfully build the docs locally with the examples inserted (please see attached screenshot)

[MarcoGorelli]

Good job, thanks! Couple of nitpicks, then good to go (EDIT: see futher review below)

[ruankie]

Just changed it to be more consistent with other function docstrings. I believe there are no extra whitespaces (as seen in screenshots)

---

pandas.DataFrame.std

---

pandas.DataFrame.sem

[MarcoGorelli]

Nice, thanks!

[jreback]

thanks @ruankie

happy to take a followup for .var to close this issue out.