DOC: added examples to DataFrame.std
State: closed

xref https://github.com/pandas-dev/pandas/issues/44162
- [x] 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
---
- [x] tests added / passed
- [x] All pre-commit linting tests pass


Labels:
name: Docs

Comments:
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 
Apologies, I am quite new to this. I just made the update. Hope it works now.
> @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
```
Thanks, @MarcoGorelli.

I am having trouble building the docs locally. I have tried creating a [development environment](https://pandas.pydata.org/docs/development/contributing_environment.html#contributing-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'
```
you need to rebuild the C extensions

```
python setup.py build_ext -j 4
```
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:

```python
@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.
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
Finally managed to successfully build the docs locally with the examples inserted (please see attached screenshot)

![std_examples](https://user-images.githubusercontent.com/58558211/139668390-22563876-d323-47fd-9017-82af24e6b185.PNG)


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`

![std](https://user-images.githubusercontent.com/58558211/139671791-06205570-6744-47d3-85fe-0259f914f622.PNG)

---
`pandas.DataFrame.sem`

![sem](https://user-images.githubusercontent.com/58558211/139671851-ad14f857-7ddc-468a-a8f7-09c7c1e4e89f.PNG)



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