DOC: CategoricalIndex doc string
State: closed

Improvements to the doc string of ``CategoricalIndex`` .

Labels:
name: Docs
name: Categorical
description: Categorical Data Type

Comments:
Hello @topper-123! Thanks for updating the PR.



Cheers ! There are no PEP8 issues in this Pull Request. :beers: 

##### Comment last updated on February 19, 2019 at 08:24 Hours UTC
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24852?src=pr&el=h1) Report
> Merging [#24852](https://codecov.io/gh/pandas-dev/pandas/pull/24852?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/01e7872b018f8ceb1c5d1217caf03d5ba4da3602?src=pr&el=desc) will **decrease** coverage by `<.01%`.
> The diff coverage is `n/a`.

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

```diff
@@            Coverage Diff             @@
##           master   #24852      +/-   ##
==========================================
- Coverage   92.39%   92.39%   -0.01%     
==========================================
  Files         166      166              
  Lines       52391    52391              
==========================================
- Hits        48407    48406       -1     
- Misses       3984     3985       +1
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.81% <ø> (ø)` | :arrow_up: |
| #single | `42.9% <ø> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/24852?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/indexes/category.py](https://codecov.io/gh/pandas-dev/pandas/pull/24852/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9jYXRlZ29yeS5weQ==) | `98.61% <ø> (ø)` | :arrow_up: |
| [pandas/util/testing.py](https://codecov.io/gh/pandas-dev/pandas/pull/24852/diff?src=pr&el=tree#diff-cGFuZGFzL3V0aWwvdGVzdGluZy5weQ==) | `88.04% <0%> (-0.1%)` | :arrow_down: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24852?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/24852?src=pr&el=footer). Last update [01e7872...aa16d5c](https://codecov.io/gh/pandas-dev/pandas/pull/24852?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/24852?src=pr&el=h1) Report
> Merging [#24852](https://codecov.io/gh/pandas-dev/pandas/pull/24852?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/f74aba614554d1de4d7986fef6296a4eda951ac9?src=pr&el=desc) will **increase** coverage by `<.01%`.
> The diff coverage is `n/a`.

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

```diff
@@            Coverage Diff             @@
##           master   #24852      +/-   ##
==========================================
+ Coverage   91.73%   91.73%   +<.01%     
==========================================
  Files         173      173              
  Lines       52839    52839              
==========================================
+ Hits        48472    48473       +1     
+ Misses       4367     4366       -1
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.29% <ø> (ø)` | :arrow_up: |
| #single | `41.74% <ø> (+0.01%)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/24852?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/indexes/category.py](https://codecov.io/gh/pandas-dev/pandas/pull/24852/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9jYXRlZ29yeS5weQ==) | `98.61% <ø> (ø)` | :arrow_up: |
| [pandas/util/testing.py](https://codecov.io/gh/pandas-dev/pandas/pull/24852/diff?src=pr&el=tree#diff-cGFuZGFzL3V0aWwvdGVzdGluZy5weQ==) | `87.66% <0%> (+0.09%)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24852?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/24852?src=pr&el=footer). Last update [f74aba6...76970f3](https://codecov.io/gh/pandas-dev/pandas/pull/24852?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

The validation output is

```
################################################################################
################################## Validation ##################################
################################################################################

3 Errors found:
        Parameters {fastpath} not documented
        Parameter "dtype" type should use "str" instead of "string"
        Examples do not pass tests

################################################################################
################################### Doctests ###################################
################################################################################

**********************************************************************
Line 73, in pandas.CategoricalIndex
Failed example:
    pd.CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'])
Expected:
    CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'], categories=['a', 'b', 'c'], ordered=False, dtype='category')  # noqa
Got:
    CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'], categories=['a', 'b', 'c'], ordered=False, dtype='category')
**********************************************************************
Line 79, in pandas.CategoricalIndex
Failed example:
    pd.CategoricalIndex(c)
Expected:
    CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'], categories=['a', 'b', 'c'], ordered=False, dtype='category')  # noqa
Got:
    CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'], categories=['a', 'b', 'c'], ordered=False, dtype='category')
**********************************************************************
Line 87, in pandas.CategoricalIndex
Failed example:
    ci
Expected:
    CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'], categories=['c', 'b', 'a'], ordered=True, dtype='category')  # noqa
Got:
    CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'], categories=['c', 'b', 'a'], ordered=True, dtype='category')
```

1. Fastpath is deprecated, so it's ok not to add it to the doc string
2. The dtype "string" is a ok, as this is a free text not a type.
3. The examples do not pass the tests, because of the ``# noqa`` part. That is needed to pass flake8.

so I think those reported errors are aceptable?
For fast path best to document as a deprecated argument. For sure want to use `str` instead of `string` and can you just remove the `#noqa` directive? On quick glance didn't see the utility of it
> For fast path best to document as a deprecated argument.

fastpath isn't documented in any other instances where it's used, even where it's not deprecated. For example Series accepts a fastpath parameter, but it's not documented in its doc string.

> For sure want to use str instead of string 

Alright.

> and can you just remove the #noqa directive? On quick glance didn't see the utility of it

The output from CategoricalIndex is >80 characters, so the linter complains about line length without the noqa. I don't like adding noqa either, but CategoricalIndex very fast becomes wider that 80 lines, so don't see how to avoid it using noqa, given how the repr of CategoricalIndex is set up currently. 

IMO the line breaks for CategoricalIndex should be better enforced, so it's < pd.options.display.width. That could be an idea for a future PR?
OK fine with skipping fastpath for now; may be actually removed before we get full LINTing on docstrings anyway.

For CategoricalIndex repr you should see other examples within the module on how to show this which you can emulate
Can you merge master and address last comment?
Closing as stale; ping if you'd like to continue
@WillAyd since this is maybe not yet perfect, but still a significant improvement compared to status-quo, I would rather just merge it instead of closing, if that is fine with you.

> For CategoricalIndex repr you should see other examples within the module on how to show this which you can emulate

The other docstring examples wrap the output over multiple lines. So that avoids the `# noqa`, but then does not pass the doctests I assume. 
Doesn't matter too much which way we use here, but in any case: I would say this is a bug in the index repr (that it doesn't follow the max width), and not something that can be solved in this PR.

I merged master and maded some fixes.

Had a single question, but otherwise I approve the fixes by @jorisvandenbossche. This will make the doc string better. That the repr is over 80 character is a seperate issue. I'll file an issue on that.

EDIT: An issue on this already exists at #12066.
Sorry missed the ping but sure agreed this is an improvement and can move forward. Thanks @topper-123 for the original PR and @jorisvandenbossche for continuing along