DOC: better document Dtypes docstrings + avoid sphinx warnings
State: closed

- Use ``class_without_autosummary`` template for the dtypes (similar to what `CategoricalDtype` already did) to avoid a bunch of sphinx warnings
- Therefore, explicitly list some attributes in the docstrings (for now, I went with only documenting the dtype-specific "metadata")
- And while at it, I also gave the docstrings an update (documenting the parameters, etc)
- And for doing the above, turned some metadata attributes of the dtypes into properties, so they 1) can be documented (have a docstring) b) cannot be set by the user (xref https://github.com/pandas-dev/pandas/issues/26096)

Labels:
name: Docs
name: Dtype Conversions
description: Unexpected or buggy dtype conversions

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/26067?src=pr&el=h1) Report
> Merging [#26067](https://codecov.io/gh/pandas-dev/pandas/pull/26067?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/d9c9e2f01ab53de2ba4031367bc570ce66dac374?src=pr&el=desc) will **decrease** coverage by `51.2%`.
> The diff coverage is `85.71%`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/26067/graphs/tree.svg?width=650&token=eZ4WkYLtcO&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/26067?src=pr&el=tree)

```diff
@@             Coverage Diff             @@
##           master   #26067       +/-   ##
===========================================
- Coverage   91.95%   40.75%   -51.21%     
===========================================
  Files         175      175               
  Lines       52427    52514       +87     
===========================================
- Hits        48208    21400    -26808     
- Misses       4219    31114    +26895
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `?` | |
| #single | `40.75% <85.71%> (-0.12%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/26067?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/arrays/sparse.py](https://codecov.io/gh/pandas-dev/pandas/pull/26067/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL3NwYXJzZS5weQ==) | `40.47% <ø> (-51.84%)` | :arrow_down: |
| [pandas/core/arrays/integer.py](https://codecov.io/gh/pandas-dev/pandas/pull/26067/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL2ludGVnZXIucHk=) | `44.18% <100%> (-52.15%)` | :arrow_down: |
| [pandas/core/dtypes/dtypes.py](https://codecov.io/gh/pandas-dev/pandas/pull/26067/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZHR5cGVzL2R0eXBlcy5weQ==) | `73.86% <85%> (-22.49%)` | :arrow_down: |
| [pandas/io/formats/latex.py](https://codecov.io/gh/pandas-dev/pandas/pull/26067/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2Zvcm1hdHMvbGF0ZXgucHk=) | `0% <0%> (-100%)` | :arrow_down: |
| [pandas/io/sas/sas\_constants.py](https://codecov.io/gh/pandas-dev/pandas/pull/26067/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL3Nhcy9zYXNfY29uc3RhbnRzLnB5) | `0% <0%> (-100%)` | :arrow_down: |
| [pandas/core/groupby/categorical.py](https://codecov.io/gh/pandas-dev/pandas/pull/26067/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ3JvdXBieS9jYXRlZ29yaWNhbC5weQ==) | `0% <0%> (-100%)` | :arrow_down: |
| [pandas/tseries/plotting.py](https://codecov.io/gh/pandas-dev/pandas/pull/26067/diff?src=pr&el=tree#diff-cGFuZGFzL3RzZXJpZXMvcGxvdHRpbmcucHk=) | `0% <0%> (-100%)` | :arrow_down: |
| [pandas/tseries/converter.py](https://codecov.io/gh/pandas-dev/pandas/pull/26067/diff?src=pr&el=tree#diff-cGFuZGFzL3RzZXJpZXMvY29udmVydGVyLnB5) | `0% <0%> (-100%)` | :arrow_down: |
| [pandas/io/formats/html.py](https://codecov.io/gh/pandas-dev/pandas/pull/26067/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2Zvcm1hdHMvaHRtbC5weQ==) | `0% <0%> (-99.37%)` | :arrow_down: |
| [pandas/io/sas/sas7bdat.py](https://codecov.io/gh/pandas-dev/pandas/pull/26067/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL3Nhcy9zYXM3YmRhdC5weQ==) | `0% <0%> (-91.16%)` | :arrow_down: |
| ... and [135 more](https://codecov.io/gh/pandas-dev/pandas/pull/26067/diff?src=pr&el=tree-more) | |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/26067?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/26067?src=pr&el=footer). Last update [d9c9e2f...8818681](https://codecov.io/gh/pandas-dev/pandas/pull/26067?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/26067?src=pr&el=h1) Report
> Merging [#26067](https://codecov.io/gh/pandas-dev/pandas/pull/26067?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/f53bb061939fb54d6c826c4db408c458d3d2a1db?src=pr&el=desc) will **decrease** coverage by `<.01%`.
> The diff coverage is `100%`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/26067/graphs/tree.svg?width=650&token=eZ4WkYLtcO&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/26067?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #26067      +/-   ##
==========================================
- Coverage   91.99%   91.98%   -0.01%     
==========================================
  Files         175      175              
  Lines       52383    52394      +11     
==========================================
+ Hits        48188    48196       +8     
- Misses       4195     4198       +3
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.54% <100%> (ø)` | :arrow_up: |
| #single | `40.74% <60%> (-0.15%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/26067?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/arrays/sparse.py](https://codecov.io/gh/pandas-dev/pandas/pull/26067/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL3NwYXJzZS5weQ==) | `92.3% <ø> (ø)` | :arrow_up: |
| [pandas/core/dtypes/dtypes.py](https://codecov.io/gh/pandas-dev/pandas/pull/26067/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZHR5cGVzL2R0eXBlcy5weQ==) | `96.42% <100%> (+0.08%)` | :arrow_up: |
| [pandas/core/arrays/integer.py](https://codecov.io/gh/pandas-dev/pandas/pull/26067/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL2ludGVnZXIucHk=) | `96.34% <100%> (+0.01%)` | :arrow_up: |
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/26067/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `75% <0%> (-12.5%)` | :arrow_down: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/26067/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `96.9% <0%> (-0.12%)` | :arrow_down: |
| [pandas/util/testing.py](https://codecov.io/gh/pandas-dev/pandas/pull/26067/diff?src=pr&el=tree#diff-cGFuZGFzL3V0aWwvdGVzdGluZy5weQ==) | `90.71% <0%> (+0.1%)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/26067?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/26067?src=pr&el=footer). Last update [f53bb06...c8ae0c9](https://codecov.io/gh/pandas-dev/pandas/pull/26067?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

@jreback could you take a look at this, if you have some time? (specifically the actual code changes in the dtypes, as this might have some implications for pickling)
> why exactly is this needed? e

It's also doing the same as what is already done in DatetimeTZDtype:

https://github.com/pandas-dev/pandas/blob/455a2cdc4808890dd7eea41494100f48f34794d5/pandas/core/dtypes/dtypes.py#L720-L723

I was only wondering if we need to worry about old pickle compat, as the above code I am showing was done in the initial implementation of DatetimeTZDtype, while for PeriodDtype that I am changing here, we already have released versions without this.
right, see my comment above, I *think* that this might just work if you move the private attributes into _metadata (and leave the accessors as propertys)
@jreback are you fine with merging this as is? 
It is consistent with how the existing CategoricalDtype and DatetimeTZDtype handle pickling compat, so I think it is fine. We could try to clean it up a bit by moving some part to the base PandasExtensionDtype, but that could also be done separate.
something faiking merge on green
thanks @jorisvandenbossche