Repository: pandas-dev/pandas
Pull request: DOC: Fix flake8 issues in categorical.rst
- [x] closes #23793
- [ ] tests added / passed
- [ ] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry


Problem statement:
DOC: Fix format of categorical.rst
Our documentation should follow the PEP-8 standard, but for historical reasons there are many formats that don't. We should fix them now.

This issue is to fix the format of `doc/source/categorical.rst`. To find the errors, first is required to install a newer version of `flake8-rst`:
```
conda install -c conda-forge flake8-rst=0.5.0
```

Then, all the errors can be obtained with:
```
$ flake8-rst doc/source/categorical.rst
doc/source/categorical.rst:63:23: E231 missing whitespace after ','
doc/source/categorical.rst:63:27: E231 missing whitespace after ','
doc/source/categorical.rst:63:31: E231 missing whitespace after ','
doc/source/categorical.rst:70:27: E231 missing whitespace after ':'
doc/source/categorical.rst:70:32: E231 missing whitespace after ','
doc/source/categorical.rst:70:36: E231 missing whitespace after ','
doc/source/categorical.rst:70:40: E231 missing whitespace after ','
doc/source/categorical.rst:89:34: E231 missing whitespace after ','
doc/source/categorical.rst:89:38: E231 missing whitespace after ','
doc/source/categorical.rst:89:42: E231 missing whitespace after ','
doc/source/categorical.rst:89:64: E231 missing whitespace after ','
doc/source/categorical.rst:89:68: E231 missing whitespace after ','
doc/source/categorical.rst:93:27: E231 missing whitespace after ':'
doc/source/categorical.rst:93:32: E231 missing whitespace after ','
doc/source/categorical.rst:93:36: E231 missing whitespace after ','
doc/source/categorical.rst:93:40: E231 missing whitespace after ','
doc/source/categorical.rst:157:5: E402 module level import not at top of file
doc/source/categorical.rst:189:35: E231 missing whitespace after ','
doc/source/categorical.rst:189:49: E231 missing whitespace after ','
doc/source/categorical.rst:190:84: E501 line too long (80 > 79 characters)
doc/source/categorical.rst:201:23: E231 missing whitespace after ','
doc/source/categorical.rst:201:27: E231 missing whitespace after ','
doc/source/categorical.rst:201:31: E231 missing whitespace after ','
doc/source/categorical.rst:238:4: E402 module level import not at top of file
doc/source/categorical.rst:271:32: E241 multiple spaces after ','
doc/source/categorical.rst:296:29: E231 missing whitespace after ':'
doc/source/categorical.rst:296:38: E231 missing whitespace after ':'
doc/source/categorical.rst:312:23: E231 missing whitespace after ','
doc/source/categorical.rst:312:27: E231 missing whitespace after ','
doc/source/categorical.rst:312:31: E231 missing whitespace after ','
doc/source/categorical.rst:320:38: E231 missing whitespace after ','
doc/source/categorical.rst:320:42: E231 missing whitespace after ','
doc/source/categorical.rst:320:46: E231 missing whitespace after ','
doc/source/categorical.rst:320:68: E231 missing whitespace after ','
doc/source/categorical.rst:320:72: E231 missing whitespace after ','
doc/source/categorical.rst:357:23: E231 missing whitespace after ','
doc/source/categorical.rst:357:27: E231 missing whitespace after ','
doc/source/categorical.rst:357:31: E231 missing whitespace after ','
doc/source/categorical.rst:361:35: E231 missing whitespace after ','
doc/source/categorical.rst:361:37: E231 missing whitespace after ','
doc/source/categorical.rst:381:30: E231 missing whitespace after ','
doc/source/categorical.rst:381:32: E231 missing whitespace after ','
doc/source/categorical.rst:390:30: E231 missing whitespace after ','
doc/source/categorical.rst:390:32: E231 missing whitespace after ','
doc/source/categorical.rst:425:38: E231 missing whitespace after ','
doc/source/categorical.rst:425:42: E231 missing whitespace after ','
doc/source/categorical.rst:425:64: E231 missing whitespace after ','
doc/source/categorical.rst:425:68: E231 missing whitespace after ','
doc/source/categorical.rst:425:72: E231 missing whitespace after ','
doc/source/categorical.rst:439:25: E231 missing whitespace after ','
doc/source/categorical.rst:439:31: E231 missing whitespace after ','
doc/source/categorical.rst:441:36: E231 missing whitespace after ','
doc/source/categorical.rst:441:42: E231 missing whitespace after ','
doc/source/categorical.rst:441:50: E231 missing whitespace after ','
doc/source/categorical.rst:459:38: E231 missing whitespace after ','
doc/source/categorical.rst:459:42: E231 missing whitespace after ','
doc/source/categorical.rst:459:46: E231 missing whitespace after ','
doc/source/categorical.rst:461:23: E231 missing whitespace after ','
doc/source/categorical.rst:461:27: E231 missing whitespace after ','
doc/source/categorical.rst:461:31: E231 missing whitespace after ','
doc/source/categorical.rst:481:21: E231 missing whitespace after ','
doc/source/categorical.rst:481:23: E231 missing whitespace after ','
doc/source/categorical.rst:481:25: E231 missing whitespace after ','
doc/source/categorical.rst:482:32: E231 missing whitespace after ','
doc/source/categorical.rst:482:34: E231 missing whitespace after ','
doc/source/categorical.rst:499:21: E231 missing whitespace after ','
doc/source/categorical.rst:499:23: E231 missing whitespace after ','
doc/source/categorical.rst:499:25: E231 missing whitespace after ','
doc/source/categorical.rst:500:36: E231 missing whitespace after ','
doc/source/categorical.rst:500:38: E231 missing whitespace after ','
doc/source/categorical.rst:529:27: E203 whitespace before ':'
doc/source/categorical.rst:529:78: E231 missing whitespace after ','
doc/source/categorical.rst:529:82: E231 missing whitespace after ','
doc/source/categorical.rst:529:83: E501 line too long (99 > 79 characters)
doc/source/categorical.rst:530:27: E203 whitespace before ':'
doc/source/categorical.rst:530:32: E231 missing whitespace after ','
doc/source/categorical.rst:530:34: E231 missing whitespace after ','
doc/source/categorical.rst:530:36: E231 missing whitespace after ','
doc/source/categorical.rst:530:38: E231 missing whitespace after ','
doc/source/categorical.rst:530:40: E231 missing whitespace after ','
doc/source/categorical.rst:530:42: E231 missing whitespace after ','
doc/source/categorical.rst:530:44: E231 missing whitespace after ','
doc/source/categorical.rst:530:47: E202 whitespace before '}'
doc/source/categorical.rst:537:51: E231 missing whitespace after ','
doc/source/categorical.rst:537:55: E231 missing whitespace after ','
doc/source/categorical.rst:538:27: E231 missing whitespace after ','
doc/source/categorical.rst:563:23: E231 missing whitespace after ','
doc/source/categorical.rst:563:25: E231 missing whitespace after ','
doc/source/categorical.rst:566:28: E231 missing whitespace after ','
doc/source/categorical.rst:566:30: E231 missing whitespace after ','
doc/source/categorical.rst:569:29: E231 missing whitespace after ','
doc/source/categorical.rst:569:31: E231 missing whitespace after ','
doc/source/categorical.rst:589:23: E231 missing whitespace after ','
doc/source/categorical.rst:589:25: E231 missing whitespace after ','
doc/source/categorical.rst:599:10: E111 indentation is not a multiple of four
doc/source/categorical.rst:607:23: E231 missing whitespace after ','
doc/source/categorical.rst:607:25: E231 missing whitespace after ','
doc/source/categorical.rst:612:10: E111 indentation is not a multiple of four
doc/source/categorical.rst:635:38: E231 missing whitespace after ','
doc/source/categorical.rst:635:42: E231 missing whitespace after ','
doc/source/categorical.rst:635:46: E231 missing whitespace after ','
doc/source/categorical.rst:635:68: E231 missing whitespace after ','
doc/source/categorical.rst:635:72: E231 missing whitespace after ','
doc/source/categorical.rst:635:76: E231 missing whitespace after ','
doc/source/categorical.rst:642:31: E231 missing whitespace after ','
doc/source/categorical.rst:642:35: E231 missing whitespace after ','
doc/source/categorical.rst:642:39: E231 missing whitespace after ','
doc/source/categorical.rst:642:43: E231 missing whitespace after ','
doc/source/categorical.rst:642:47: E231 missing whitespace after ','
doc/source/categorical.rst:642:51: E231 missing whitespace after ','
doc/source/categorical.rst:642:73: E231 missing whitespace after ','
doc/source/categorical.rst:642:77: E231 missing whitespace after ','
doc/source/categorical.rst:642:81: E231 missing whitespace after ','
doc/source/categorical.rst:642:84: E501 line too long (82 > 79 characters)
doc/source/categorical.rst:643:30: E231 missing whitespace after ':'
doc/source/categorical.rst:643:35: E231 missing whitespace after ','
doc/source/categorical.rst:643:44: E231 missing whitespace after ':'
doc/source/categorical.rst:643:47: E231 missing whitespace after ','
doc/source/categorical.rst:643:49: E231 missing whitespace after ','
doc/source/categorical.rst:643:51: E231 missing whitespace after ','
doc/source/categorical.rst:643:53: E231 missing whitespace after ','
doc/source/categorical.rst:643:55: E231 missing whitespace after ','
doc/source/categorical.rst:643:57: E231 missing whitespace after ','
doc/source/categorical.rst:646:32: E231 missing whitespace after ','
doc/source/categorical.rst:646:36: E231 missing whitespace after ','
doc/source/categorical.rst:646:40: E231 missing whitespace after ','
doc/source/categorical.rst:646:62: E231 missing whitespace after ','
doc/source/categorical.rst:646:66: E231 missing whitespace after ','
doc/source/categorical.rst:647:31: E231 missing whitespace after ':'
doc/source/categorical.rst:647:37: E231 missing whitespace after ','
doc/source/categorical.rst:647:41: E231 missing whitespace after ':'
doc/source/categorical.rst:647:46: E231 missing whitespace after ','
doc/source/categorical.rst:647:50: E231 missing whitespace after ','
doc/source/categorical.rst:647:54: E231 missing whitespace after ','
doc/source/categorical.rst:647:69: E231 missing whitespace after ':'
doc/source/categorical.rst:647:72: E231 missing whitespace after ','
doc/source/categorical.rst:647:74: E231 missing whitespace after ','
doc/source/categorical.rst:647:76: E231 missing whitespace after ','
doc/source/categorical.rst:648:24: E231 missing whitespace after ','
doc/source/categorical.rst:655:34: E231 missing whitespace after ','
doc/source/categorical.rst:655:38: E231 missing whitespace after ','
doc/source/categorical.rst:655:42: E231 missing whitespace after ','
doc/source/categorical.rst:655:64: E231 missing whitespace after ','
doc/source/categorical.rst:655:68: E231 missing whitespace after ','
doc/source/categorical.rst:656:27: E231 missing whitespace after ':'
doc/source/categorical.rst:656:35: E231 missing whitespace after ','
doc/source/categorical.rst:656:39: E231 missing whitespace after ':'
doc/source/categorical.rst:656:44: E231 missing whitespace after ','
doc/source/categorical.rst:656:48: E231 missing whitespace after ','
doc/source/categorical.rst:656:52: E231 missing whitespace after ','
doc/source/categorical.rst:656:67: E231 missing whitespace after ':'
doc/source/categorical.rst:656:70: E231 missing whitespace after ','
doc/source/categorical.rst:656:72: E231 missing whitespace after ','
doc/source/categorical.rst:656:74: E231 missing whitespace after ','
doc/source/categorical.rst:674:24: E231 missing whitespace after ','
doc/source/categorical.rst:674:28: E231 missing whitespace after ','
doc/source/categorical.rst:674:32: E231 missing whitespace after ','
doc/source/categorical.rst:674:36: E231 missing whitespace after ','
doc/source/categorical.rst:674:40: E231 missing whitespace after ','
doc/source/categorical.rst:674:44: E231 missing whitespace after ','
doc/source/categorical.rst:674:48: E231 missing whitespace after ','
doc/source/categorical.rst:675:26: E231 missing whitespace after ','
doc/source/categorical.rst:675:30: E231 missing whitespace after ','
doc/source/categorical.rst:675:34: E231 missing whitespace after ','
doc/source/categorical.rst:675:38: E231 missing whitespace after ','
doc/source/categorical.rst:675:42: E231 missing whitespace after ','
doc/source/categorical.rst:675:46: E231 missing whitespace after ','
doc/source/categorical.rst:676:11: E225 missing whitespace around operator
doc/source/categorical.rst:676:15: E231 missing whitespace after ','
doc/source/categorical.rst:676:17: E231 missing whitespace after ','
doc/source/categorical.rst:676:19: E231 missing whitespace after ','
doc/source/categorical.rst:676:21: E231 missing whitespace after ','
doc/source/categorical.rst:676:23: E231 missing whitespace after ','
doc/source/categorical.rst:676:25: E231 missing whitespace after ','
doc/source/categorical.rst:677:30: E231 missing whitespace after ':'
doc/source/categorical.rst:677:35: E231 missing whitespace after ','
doc/source/categorical.rst:677:44: E231 missing whitespace after ':'
doc/source/categorical.rst:678:16: E231 missing whitespace after ','
doc/source/categorical.rst:679:16: E231 missing whitespace after ','
doc/source/categorical.rst:680:19: E231 missing whitespace after ','
doc/source/categorical.rst:696:13: E231 missing whitespace after ','
doc/source/categorical.rst:697:37: E231 missing whitespace after ','
doc/source/categorical.rst:697:41: E231 missing whitespace after ','
doc/source/categorical.rst:698:14: E231 missing whitespace after ','
doc/source/categorical.rst:698:22: E261 at least two spaces before inline comment
doc/source/categorical.rst:709:17: E231 missing whitespace after ','
doc/source/categorical.rst:763:24: E231 missing whitespace after ','
doc/source/categorical.rst:763:28: E231 missing whitespace after ','
doc/source/categorical.rst:763:32: E231 missing whitespace after ','
doc/source/categorical.rst:763:36: E231 missing whitespace after ','
doc/source/categorical.rst:763:40: E231 missing whitespace after ','
doc/source/categorical.rst:763:44: E231 missing whitespace after ','
doc/source/categorical.rst:764:31: E231 missing whitespace after ','
doc/source/categorical.rst:764:35: E231 missing whitespace after ','
doc/source/categorical.rst:764:39: E231 missing whitespace after ','
doc/source/categorical.rst:764:43: E231 missing whitespace after ','
doc/source/categorical.rst:764:47: E231 missing whitespace after ','
doc/source/categorical.rst:764:51: E231 missing whitespace after ','
doc/source/categorical.rst:764:73: E231 missing whitespace after ','
doc/source/categorical.rst:765:16: E231 missing whitespace after ','
doc/source/categorical.rst:765:18: E231 missing whitespace after ','
doc/source/categorical.rst:765:20: E231 missing whitespace after ','
doc/source/categorical.rst:765:22: E231 missing whitespace after ','
doc/source/categorical.rst:765:24: E231 missing whitespace after ','
doc/source/categorical.rst:765:26: E231 missing whitespace after ','
doc/source/categorical.rst:766:30: E231 missing whitespace after ':'
doc/source/categorical.rst:766:35: E231 missing whitespace after ','
doc/source/categorical.rst:766:44: E231 missing whitespace after ':'
doc/source/categorical.rst:768:16: E231 missing whitespace after ','
doc/source/categorical.rst:768:27: E231 missing whitespace after ','
doc/source/categorical.rst:768:30: E231 missing whitespace after ','
doc/source/categorical.rst:768:35: E231 missing whitespace after ','
doc/source/categorical.rst:771:20: E231 missing whitespace after ','
doc/source/categorical.rst:771:31: E231 missing whitespace after ','
doc/source/categorical.rst:771:34: E231 missing whitespace after ','
doc/source/categorical.rst:771:39: E231 missing whitespace after ','
doc/source/categorical.rst:779:19: E231 missing whitespace after ','
doc/source/categorical.rst:779:49: E231 missing whitespace after ','
doc/source/categorical.rst:779:71: E231 missing whitespace after ','
doc/source/categorical.rst:782:23: E231 missing whitespace after ','
doc/source/categorical.rst:782:53: E231 missing whitespace after ','
doc/source/categorical.rst:782:75: E231 missing whitespace after ','
doc/source/categorical.rst:782:79: E231 missing whitespace after ','
doc/source/categorical.rst:782:84: E501 line too long (80 > 79 characters)
doc/source/categorical.rst:790:27: E231 missing whitespace after ':'
doc/source/categorical.rst:790:30: E231 missing whitespace after ','
doc/source/categorical.rst:790:32: E231 missing whitespace after ','
doc/source/categorical.rst:790:34: E231 missing whitespace after ','
doc/source/categorical.rst:790:36: E231 missing whitespace after ','
doc/source/categorical.rst:790:44: E231 missing whitespace after ':'
doc/source/categorical.rst:790:49: E231 missing whitespace after ','
doc/source/categorical.rst:790:53: E231 missing whitespace after ','
doc/source/categorical.rst:790:57: E231 missing whitespace after ','
doc/source/categorical.rst:790:61: E231 missing whitespace after ','
doc/source/categorical.rst:791:15: E231 missing whitespace after ','
doc/source/categorical.rst:791:42: E231 missing whitespace after ','
doc/source/categorical.rst:791:64: E231 missing whitespace after ','
doc/source/categorical.rst:792:15: E231 missing whitespace after ','
doc/source/categorical.rst:792:42: E231 missing whitespace after ','
doc/source/categorical.rst:792:64: E231 missing whitespace after ','
doc/source/categorical.rst:806:25: E231 missing whitespace after ','
doc/source/categorical.rst:807:14: E231 missing whitespace after ','
doc/source/categorical.rst:808:30: E231 missing whitespace after ':'
doc/source/categorical.rst:808:42: E231 missing whitespace after ':'
doc/source/categorical.rst:809:24: E231 missing whitespace after ','
doc/source/categorical.rst:818:47: E231 missing whitespace after ','
doc/source/categorical.rst:820:22: E231 missing whitespace after ','
doc/source/categorical.rst:843:5: E402 module level import not at top of file
doc/source/categorical.rst:979:5: E402 module level import not at top of file
doc/source/categorical.rst:988:30: E231 missing whitespace after ':'
doc/source/categorical.rst:988:40: E231 missing whitespace after ':'
doc/source/categorical.rst:988:43: E231 missing whitespace after ','
doc/source/categorical.rst:988:45: E231 missing whitespace after ','
doc/source/categorical.rst:988:47: E231 missing whitespace after ','
doc/source/categorical.rst:988:49: E231 missing whitespace after ','
doc/source/categorical.rst:988:51: E231 missing whitespace after ','
doc/source/categorical.rst:996:84: E501 line too long (82 > 79 characters)
doc/source/categorical.rst:1065:24: E231 missing whitespace after ','
doc/source/categorical.rst:1065:31: E226 missing whitespace around arithmetic operator
doc/source/categorical.rst:1108:10: E111 indentation is not a multiple of four
doc/source/categorical.rst:1129:36: E231 missing whitespace after ','
doc/source/categorical.rst:1129:38: E231 missing whitespace after ','
doc/source/categorical.rst:1129:40: E231 missing whitespace after ','
doc/source/categorical.rst:1132:9: E265 block comment should start with '# '
doc/source/categorical.rst:1134:10: E111 indentation is not a multiple of four
doc/source/categorical.rst:1148:27: E231 missing whitespace after ':'
doc/source/categorical.rst:1148:30: E231 missing whitespace after ','
doc/source/categorical.rst:1148:32: E231 missing whitespace after ','
doc/source/categorical.rst:1148:34: E231 missing whitespace after ','
doc/source/categorical.rst:1149:27: E231 missing whitespace after ':'
doc/source/categorical.rst:1149:32: E231 missing whitespace after ','
doc/source/categorical.rst:1149:36: E231 missing whitespace after ','
doc/source/categorical.rst:1149:40: E231 missing whitespace after ','
doc/source/categorical.rst:1150:30: E231 missing whitespace after ':'
doc/source/categorical.rst:1150:48: E231 missing whitespace after ','
doc/source/categorical.rst:1150:50: E231 missing whitespace after ','
doc/source/categorical.rst:1150:52: E231 missing whitespace after ','
doc/source/categorical.rst:1167:29: E231 missing whitespace after ','
doc/source/categorical.rst:1167:31: E231 missing whitespace after ','
doc/source/categorical.rst:1167:33: E231 missing whitespace after ','
doc/source/categorical.rst:1167:51: E231 missing whitespace after ','
doc/source/categorical.rst:1167:53: E231 missing whitespace after ','
doc/source/categorical.rst:1167:55: E231 missing whitespace after ','
doc/source/categorical.rst:1168:19: E231 missing whitespace after ','
doc/source/categorical.rst:1168:23: E231 missing whitespace after ','
doc/source/categorical.rst:1168:27: E231 missing whitespace after ','
doc/source/categorical.rst:1169:16: E231 missing whitespace after ','
doc/source/categorical.rst:1169:18: E231 missing whitespace after ','
doc/source/categorical.rst:1169:20: E231 missing whitespace after ','
doc/source/categorical.rst:1170:33: E231 missing whitespace after ':'
doc/source/categorical.rst:1170:51: E231 missing whitespace after ':'
doc/source/categorical.rst:1184:28: E231 missing whitespace after ','
doc/source/categorical.rst:1184:30: E231 missing whitespace after ','
doc/source/categorical.rst:1184:32: E231 missing whitespace after ','
doc/source/categorical.rst:1184:51: E231 missing whitespace after ','
doc/source/categorical.rst:1184:53: E231 missing whitespace after ','
doc/source/categorical.rst:1184:55: E231 missing whitespace after ','
doc/source/categorical.rst:1184:57: E231 missing whitespace after ','
doc/source/categorical.rst:1190:34: E231 missing whitespace after ','
doc/source/categorical.rst:1190:36: E231 missing whitespace after ','
doc/source/categorical.rst:1190:38: E231 missing whitespace after ','
doc/source/categorical.rst:1190:40: E231 missing whitespace after ','
doc/source/categorical.rst:1197:28: E231 missing whitespace after ','
doc/source/categorical.rst:1197:30: E231 missing whitespace after ','
doc/source/categorical.rst:1197:32: E231 missing whitespace after ','
doc/source/categorical.rst:1197:51: E231 missing whitespace after ','
doc/source/categorical.rst:1197:53: E231 missing whitespace after ','
doc/source/categorical.rst:1197:55: E231 missing whitespace after ','
doc/source/categorical.rst:1197:57: E231 missing whitespace after ','
```

After fixing this issue, the previous command should not report any error.

Hints from issue discussion:
i will take a try....
thanks @charlesdong1991

Commit message: docstring modification to remove error messages

Patch to review:
diff --git a/doc/source/categorical.rst b/doc/source/categorical.rst
index acab9de905540..ff5729fb4ae48 100644
--- a/doc/source/categorical.rst
+++ b/doc/source/categorical.rst
@@ -7,6 +7,9 @@
 
    import numpy as np
    import pandas as pd
+   from pandas.api.types import CategoricalDtype
+   from pandas.api.types import union_categoricals
+   from pandas.compat import StringIO
    np.random.seed(123456)
    np.set_printoptions(precision=4, suppress=True)
    pd.options.display.max_rows = 15
@@ -60,14 +63,14 @@ By specifying ``dtype="category"`` when constructing a ``Series``:
 
 .. ipython:: python
 
-    s = pd.Series(["a","b","c","a"], dtype="category")
+    s = pd.Series(["a", "b", "c", "a"], dtype="category")
     s
 
 By converting an existing ``Series`` or column to a ``category`` dtype:
 
 .. ipython:: python
 
-    df = pd.DataFrame({"A":["a","b","c","a"]})
+    df = pd.DataFrame({"A": ["a", "b", "c", "a"]})
     df["B"] = df["A"].astype('category')
     df
 
@@ -86,11 +89,11 @@ By passing a :class:`pandas.Categorical` object to a ``Series`` or assigning it
 
 .. ipython:: python
 
-    raw_cat = pd.Categorical(["a","b","c","a"], categories=["b","c","d"],
+    raw_cat = pd.Categorical(["a", "b", "c", "a"], categories=["b", "c", "d"],
                              ordered=False)
     s = pd.Series(raw_cat)
     s
-    df = pd.DataFrame({"A":["a","b","c","a"]})
+    df = pd.DataFrame({"A": ["a", "b", "c", "a"]})
     df["B"] = raw_cat
     df
 
@@ -154,8 +157,6 @@ of :class:`~pandas.api.types.CategoricalDtype`.
 
 .. ipython:: python
 
-    from pandas.api.types import CategoricalDtype
-
     s = pd.Series(["a", "b", "c", "a"])
     cat_type = CategoricalDtype(categories=["b", "c", "d"],
                                 ordered=True)
@@ -186,8 +187,9 @@ during normal constructor mode:
 
 .. ipython:: python
 
-    splitter = np.random.choice([0,1], 5, p=[0.5,0.5])
-    s = pd.Series(pd.Categorical.from_codes(splitter, categories=["train", "test"]))
+    splitter = np.random.choice([0, 1], 5, p=[0.5, 0.5])
+    s = pd.Series(pd.Categorical.from_codes(splitter,
+                                            categories=["train", "test"]))
 
 
 Regaining Original Data
@@ -198,7 +200,7 @@ To get back to the original ``Series`` or NumPy array, use
 
 .. ipython:: python
 
-    s = pd.Series(["a","b","c","a"])
+    s = pd.Series(["a", "b", "c", "a"])
     s
     s2 = s.astype('category')
     s2
@@ -235,8 +237,6 @@ by default.
 
 .. ipython:: python
 
-   from pandas.api.types import CategoricalDtype
-
    CategoricalDtype(['a', 'b', 'c'])
    CategoricalDtype(['a', 'b', 'c'], ordered=True)
    CategoricalDtype()
@@ -268,7 +268,7 @@ unordered categoricals, the order of the ``categories`` is not considered.
    c1 == CategoricalDtype(['b', 'c', 'a'], ordered=False)
 
    # Unequal, since the second CategoricalDtype is ordered
-   c1 == CategoricalDtype(['a',  'b', 'c'], ordered=True)
+   c1 == CategoricalDtype(['a', 'b', 'c'], ordered=True)
 
 All instances of ``CategoricalDtype`` compare equal to the string ``'category'``.
 
@@ -293,7 +293,7 @@ output to a ``Series`` or ``DataFrame`` of type ``string``.
 .. ipython:: python
 
     cat = pd.Categorical(["a", "c", "c", np.nan], categories=["b", "a", "c"])
-    df = pd.DataFrame({"cat":cat, "s":["a", "c", "c", np.nan]})
+    df = pd.DataFrame({"cat": cat, "s": ["a", "c", "c", np.nan]})
     df.describe()
     df["cat"].describe()
 
@@ -309,7 +309,7 @@ specify categories and ordering, they are inferred from the passed arguments.
 
 .. ipython:: python
 
-    s = pd.Series(["a","b","c","a"], dtype="category")
+    s = pd.Series(["a", "b", "c", "a"], dtype="category")
     s.cat.categories
     s.cat.ordered
 
@@ -317,7 +317,8 @@ It's also possible to pass in the categories in a specific order:
 
 .. ipython:: python
 
-    s = pd.Series(pd.Categorical(["a","b","c","a"], categories=["c","b","a"]))
+    s = pd.Series(pd.Categorical(["a", "b", "c", "a"],
+                  categories=["c", "b", "a"]))
     s.cat.categories
     s.cat.ordered
 
@@ -354,11 +355,11 @@ Renaming categories is done by assigning new values to the
 
 .. ipython:: python
 
-    s = pd.Series(["a","b","c","a"], dtype="category")
+    s = pd.Series(["a", "b", "c", "a"], dtype="category")
     s
     s.cat.categories = ["Group %s" % g for g in s.cat.categories]
     s
-    s = s.cat.rename_categories([1,2,3])
+    s = s.cat.rename_categories([1, 2, 3])
     s
     # You can also pass a dict-like object to map the renaming
     s = s.cat.rename_categories({1: 'x', 2: 'y', 3: 'z'})
@@ -378,7 +379,7 @@ Categories must be unique or a `ValueError` is raised:
 .. ipython:: python
 
     try:
-        s.cat.categories = [1,1,1]
+        s.cat.categories = [1, 1, 1]
     except ValueError as e:
         print("ValueError: " + str(e))
 
@@ -387,7 +388,7 @@ Categories must also not be ``NaN`` or a `ValueError` is raised:
 .. ipython:: python
 
     try:
-        s.cat.categories = [1,2,np.nan]
+        s.cat.categories = [1, 2, np.nan]
     except ValueError as e:
         print("ValueError: " + str(e))
 
@@ -422,7 +423,8 @@ Removing unused categories can also be done:
 
 .. ipython:: python
 
-    s = pd.Series(pd.Categorical(["a","b","a"], categories=["a","b","c","d"]))
+    s = pd.Series(pd.Categorical(["a", "b", "a"],
+                  categories=["a", "b", "c", "d"]))
     s
     s.cat.remove_unused_categories()
 
@@ -436,9 +438,9 @@ use :meth:`~pandas.Categorical.set_categories`.
 
 .. ipython:: python
 
-    s = pd.Series(["one","two","four", "-"], dtype="category")
+    s = pd.Series(["one", "two", "four", "-"], dtype="category")
     s
-    s = s.cat.set_categories(["one","two","three","four"])
+    s = s.cat.set_categories(["one", "two", "three", "four"])
     s
 
 .. note::
@@ -456,9 +458,9 @@ meaning and certain operations are possible. If the categorical is unordered, ``
 
 .. ipython:: python
 
-    s = pd.Series(pd.Categorical(["a","b","c","a"], ordered=False))
+    s = pd.Series(pd.Categorical(["a", "b", "c", "a"], ordered=False))
     s.sort_values(inplace=True)
-    s = pd.Series(["a","b","c","a"]).astype(
+    s = pd.Series(["a", "b", "c", "a"]).astype(
         CategoricalDtype(ordered=True)
     )
     s.sort_values(inplace=True)
@@ -478,8 +480,8 @@ This is even true for strings and numeric data:
 
 .. ipython:: python
 
-    s = pd.Series([1,2,3,1], dtype="category")
-    s = s.cat.set_categories([2,3,1], ordered=True)
+    s = pd.Series([1, 2, 3, 1], dtype="category")
+    s = s.cat.set_categories([2, 3, 1], ordered=True)
     s
     s.sort_values(inplace=True)
     s
@@ -496,8 +498,8 @@ necessarily make the sort order the same as the categories order.
 
 .. ipython:: python
 
-    s = pd.Series([1,2,3,1], dtype="category")
-    s = s.cat.reorder_categories([2,3,1], ordered=True)
+    s = pd.Series([1, 2, 3, 1], dtype="category")
+    s = s.cat.reorder_categories([2, 3, 1], ordered=True)
     s
     s.sort_values(inplace=True)
     s
@@ -526,16 +528,18 @@ The ordering of the categorical is determined by the ``categories`` of that colu
 
 .. ipython:: python
 
-   dfs = pd.DataFrame({'A' : pd.Categorical(list('bbeebbaa'), categories=['e','a','b'], ordered=True),
-                       'B' : [1,2,1,2,2,1,2,1] })
+   dfs = pd.DataFrame({'A': pd.Categorical(list('bbeebbaa'),
+                                           categories=['e', 'a', 'b'],
+                                           ordered=True),
+                       'B': [1, 2, 1, 2, 2, 1, 2, 1]})
    dfs.sort_values(by=['A', 'B'])
 
 Reordering the ``categories`` changes a future sort.
 
 .. ipython:: python
 
-   dfs['A'] = dfs['A'].cat.reorder_categories(['a','b','e'])
-   dfs.sort_values(by=['A','B'])
+   dfs['A'] = dfs['A'].cat.reorder_categories(['a', 'b', 'e'])
+   dfs.sort_values(by=['A', 'B'])
 
 Comparisons
 -----------
@@ -560,13 +564,13 @@ categories or a categorical with any list-like object, will raise a ``TypeError`
 
 .. ipython:: python
 
-    cat = pd.Series([1,2,3]).astype(
+    cat = pd.Series([1, 2, 3]).astype(
         CategoricalDtype([3, 2, 1], ordered=True)
     )
-    cat_base = pd.Series([2,2,2]).astype(
+    cat_base = pd.Series([2, 2, 2]).astype(
         CategoricalDtype([3, 2, 1], ordered=True)
     )
-    cat_base2 = pd.Series([2,2,2]).astype(
+    cat_base2 = pd.Series([2, 2, 2]).astype(
         CategoricalDtype(ordered=True)
     )
 
@@ -586,7 +590,7 @@ Equality comparisons work with any list-like object of same length and scalars:
 .. ipython:: python
 
     cat == cat_base
-    cat == np.array([1,2,3])
+    cat == np.array([1, 2, 3])
     cat == 2
 
 This doesn't work because the categories are not the same:
@@ -596,7 +600,7 @@ This doesn't work because the categories are not the same:
     try:
         cat > cat_base2
     except TypeError as e:
-         print("TypeError: " + str(e))
+        print("TypeError: " + str(e))
 
 If you want to do a "non-equality" comparison of a categorical series with a list-like object
 which is not categorical data, you need to be explicit and convert the categorical data back to
@@ -604,12 +608,12 @@ the original values:
 
 .. ipython:: python
 
-    base = np.array([1,2,3])
+    base = np.array([1, 2, 3])
 
     try:
         cat > base
     except TypeError as e:
-         print("TypeError: " + str(e))
+        print("TypeError: " + str(e))
 
     np.asarray(cat) > base
 
@@ -632,28 +636,34 @@ even if some categories are not present in the data:
 
 .. ipython:: python
 
-    s = pd.Series(pd.Categorical(["a","b","c","c"], categories=["c","a","b","d"]))
+    s = pd.Series(pd.Categorical(["a", "b", "c", "c"],
+                  categories=["c", "a", "b", "d"]))
     s.value_counts()
 
 Groupby will also show "unused" categories:
 
 .. ipython:: python
 
-    cats = pd.Categorical(["a","b","b","b","c","c","c"], categories=["a","b","c","d"])
-    df = pd.DataFrame({"cats":cats,"values":[1,2,2,2,3,4,5]})
+    cats = pd.Categorical(["a", "b", "b", "b", "c", "c", "c"],
+                          categories=["a", "b", "c", "d"])
+    df = pd.DataFrame({"cats": cats, "values": [1, 2, 2, 2, 3, 4, 5]})
     df.groupby("cats").mean()
 
-    cats2 = pd.Categorical(["a","a","b","b"], categories=["a","b","c"])
-    df2 = pd.DataFrame({"cats":cats2,"B":["c","d","c","d"], "values":[1,2,3,4]})
-    df2.groupby(["cats","B"]).mean()
+    cats2 = pd.Categorical(["a", "a", "b", "b"], categories=["a", "b", "c"])
+    df2 = pd.DataFrame({"cats": cats2,
+                        "B": ["c", "d", "c", "d"],
+                        "values": [1, 2, 3, 4]})
+    df2.groupby(["cats", "B"]).mean()
 
 
 Pivot tables:
 
 .. ipython:: python
 
-    raw_cat = pd.Categorical(["a","a","b","b"], categories=["a","b","c"])
-    df = pd.DataFrame({"A":raw_cat,"B":["c","d","c","d"], "values":[1,2,3,4]})
+    raw_cat = pd.Categorical(["a", "a", "b", "b"], categories=["a", "b", "c"])
+    df = pd.DataFrame({"A": raw_cat,
+                       "B": ["c", "d", "c", "d"],
+                       "values": [1, 2, 3, 4]})
     pd.pivot_table(df, values='values', index=['A', 'B'])
 
 Data munging
@@ -671,13 +681,14 @@ If the slicing operation returns either a ``DataFrame`` or a column of type
 
 .. ipython:: python
 
-    idx = pd.Index(["h","i","j","k","l","m","n",])
-    cats = pd.Series(["a","b","b","b","c","c","c"], dtype="category", index=idx)
-    values= [1,2,2,2,3,4,5]
-    df = pd.DataFrame({"cats":cats,"values":values}, index=idx)
-    df.iloc[2:4,:]
-    df.iloc[2:4,:].dtypes
-    df.loc["h":"j","cats"]
+    idx = pd.Index(["h", "i", "j", "k", "l", "m", "n"])
+    cats = pd.Series(["a", "b", "b", "b", "c", "c", "c"],
+                     dtype="category", index=idx)
+    values = [1, 2, 2, 2, 3, 4, 5]
+    df = pd.DataFrame({"cats": cats, "values": values}, index=idx)
+    df.iloc[2:4, :]
+    df.iloc[2:4, :].dtypes
+    df.loc["h": "j", "cats"]
     df[df["cats"] == "b"]
 
 An example where the category type is not preserved is if you take one single 
@@ -693,9 +704,9 @@ of length "1".
 
 .. ipython:: python
 
-    df.iat[0,0]
-    df["cats"].cat.categories = ["x","y","z"]
-    df.at["h","cats"] # returns a string
+    df.iat[0, 0]
+    df["cats"].cat.categories = ["x", "y", "z"]
+    df.at["h", "cats"]  # returns a string
 
 .. note::
     The is in contrast to R's `factor` function, where ``factor(c(1,2,3))[1]``
@@ -706,7 +717,7 @@ a single value:
 
 .. ipython:: python
 
-    df.loc[["h"],"cats"]
+    df.loc[["h"], "cats"]
 
 String and datetime accessors
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -760,15 +771,16 @@ value is included in the `categories`:
 
 .. ipython:: python
 
-    idx = pd.Index(["h","i","j","k","l","m","n"])
-    cats = pd.Categorical(["a","a","a","a","a","a","a"], categories=["a","b"])
-    values = [1,1,1,1,1,1,1]
-    df = pd.DataFrame({"cats":cats,"values":values}, index=idx)
+    idx = pd.Index(["h", "i", "j", "k", "l", "m", "n"])
+    cats = pd.Categorical(["a", "a", "a", "a", "a", "a", "a"],
+                          categories=["a", "b"])
+    values = [1, 1, 1, 1, 1, 1, 1]
+    df = pd.DataFrame({"cats": cats, "values": values}, index=idx)
 
-    df.iloc[2:4,:] = [["b",2],["b",2]]
+    df.iloc[2:4, :] = [["b", 2], ["b", 2]]
     df
     try:
-        df.iloc[2:4,:] = [["c",3],["c",3]]
+        df.iloc[2:4, :] = [["c", 3], ["c", 3]]
     except ValueError as e:
         print("ValueError: " + str(e))
 
@@ -776,10 +788,11 @@ Setting values by assigning categorical data will also check that the `categorie
 
 .. ipython:: python
 
-    df.loc["j":"k","cats"] = pd.Categorical(["a","a"], categories=["a","b"])
+    df.loc["j": "k", "cats"] = pd.Categorical(["a", "a"], categories=["a", "b"])
     df
     try:
-        df.loc["j":"k","cats"] = pd.Categorical(["b","b"], categories=["a","b","c"])
+        df.loc["j": "k", "cats"] = pd.Categorical(["b", "b"],
+                                                  categories=["a", "b", "c"])
     except ValueError as e:
         print("ValueError: " + str(e))
 
@@ -787,9 +800,9 @@ Assigning a ``Categorical`` to parts of a column of other types will use the val
 
 .. ipython:: python
 
-    df = pd.DataFrame({"a":[1,1,1,1,1], "b":["a","a","a","a","a"]})
-    df.loc[1:2,"a"] = pd.Categorical(["b","b"], categories=["a","b"])
-    df.loc[2:3,"b"] = pd.Categorical(["b","b"], categories=["a","b"])
+    df = pd.DataFrame({"a": [1, 1, 1, 1, 1], "b": ["a", "a", "a", "a", "a"]})
+    df.loc[1:2, "a"] = pd.Categorical(["b", "b"], categories=["a", "b"])
+    df.loc[2:3, "b"] = pd.Categorical(["b", "b"], categories=["a", "b"])
     df
     df.dtypes
 
@@ -803,10 +816,10 @@ but the categories of these categoricals need to be the same:
 
 .. ipython:: python
 
-    cat = pd.Series(["a","b"], dtype="category")
-    vals = [1,2]
-    df = pd.DataFrame({"cats":cat, "vals":vals})
-    res = pd.concat([df,df])
+    cat = pd.Series(["a", "b"], dtype="category")
+    vals = [1, 2]
+    df = pd.DataFrame({"cats": cat, "vals": vals})
+    res = pd.concat([df, df])
     res
     res.dtypes
 
@@ -815,9 +828,9 @@ In this case the categories are not the same, and therefore an error is raised:
 .. ipython:: python
 
     df_different = df.copy()
-    df_different["cats"].cat.categories = ["c","d"]
+    df_different["cats"].cat.categories = ["c", "d"]
     try:
-        pd.concat([df,df_different])
+        pd.concat([df, df_different])
     except ValueError as e:
         print("ValueError: " + str(e))
 
@@ -840,7 +853,6 @@ the categories being combined.
 
 .. ipython:: python
 
-    from pandas.api.types import union_categoricals
     a = pd.Categorical(["b", "c"])
     b = pd.Categorical(["a", "b"])
     union_categoricals([a, b])
@@ -976,7 +988,6 @@ relevant columns back to `category` and assign the right categories and categori
 .. ipython:: python
     :suppress:
 
-    from pandas.compat import StringIO
 
 .. ipython:: python
 
@@ -985,7 +996,7 @@ relevant columns back to `category` and assign the right categories and categori
     s.cat.categories = ["very good", "good", "bad"]
     # reorder the categories and add missing categories
     s = s.cat.set_categories(["very bad", "bad", "medium", "good", "very good"])
-    df = pd.DataFrame({"cats":s, "vals":[1,2,3,4,5,6]})
+    df = pd.DataFrame({"cats": s, "vals": [1, 2, 3, 4, 5, 6]})
     csv = StringIO()
     df.to_csv(csv)
     df2 = pd.read_csv(StringIO(csv.getvalue()))
@@ -993,7 +1004,8 @@ relevant columns back to `category` and assign the right categories and categori
     df2["cats"]
     # Redo the category
     df2["cats"] = df2["cats"].astype("category")
-    df2["cats"].cat.set_categories(["very bad", "bad", "medium", "good", "very good"],
+    df2["cats"].cat.set_categories(["very bad", "bad", "medium",
+                                    "good", "very good"],
                                    inplace=True)
     df2.dtypes
     df2["cats"]
@@ -1062,7 +1074,7 @@ an ``object`` dtype is a constant times the length of the data.
 
 .. ipython:: python
 
-   s = pd.Series(['foo','bar']*1000)
+   s = pd.Series(['foo', 'bar'] * 1000)
 
    # object dtype
    s.nbytes
@@ -1105,7 +1117,7 @@ NumPy itself doesn't know about the new `dtype`:
     try:
         np.dtype(dtype)
     except TypeError as e:
-         print("TypeError: " + str(e))
+        print("TypeError: " + str(e))
 
 Dtype comparisons work:
 
@@ -1126,12 +1138,12 @@ are not numeric data (even in the case that ``.categories`` is numeric).
 
 .. ipython:: python
 
-    s = pd.Series(pd.Categorical([1,2,3,4]))
+    s = pd.Series(pd.Categorical([1, 2, 3, 4]))
     try:
         np.sum(s)
-        #same with np.log(s),..
+        # same with np.log(s),..
     except TypeError as e:
-         print("TypeError: " + str(e))
+        print("TypeError: " + str(e))
 
 .. note::
     If such a function works, please file a bug at https://github.com/pandas-dev/pandas!
@@ -1145,9 +1157,9 @@ basic type) and applying along columns will also convert to object.
 
 .. ipython:: python
 
-    df = pd.DataFrame({"a":[1,2,3,4],
-                       "b":["a","b","c","d"],
-                       "cats":pd.Categorical([1,2,3,2])})
+    df = pd.DataFrame({"a": [1, 2, 3, 4],
+                       "b": ["a", "b", "c", "d"],
+                       "cats": pd.Categorical([1, 2, 3, 2])})
     df.apply(lambda row: type(row["cats"]), axis=1)
     df.apply(lambda col: col.dtype, axis=0)
 
@@ -1164,10 +1176,10 @@ Setting the index will create a ``CategoricalIndex``:
 
 .. ipython:: python
 
-    cats = pd.Categorical([1,2,3,4], categories=[4,2,3,1])
-    strings = ["a","b","c","d"]
-    values = [4,2,3,1]
-    df = pd.DataFrame({"strings":strings, "values":values}, index=cats)
+    cats = pd.Categorical([1, 2, 3, 4], categories=[4, 2, 3, 1])
+    strings = ["a", "b", "c", "d"]
+    values = [4, 2, 3, 1]
+    df = pd.DataFrame({"strings": strings, "values": values}, index=cats)
     df.index
     # This now sorts by the categories order
     df.sort_index()
@@ -1181,20 +1193,20 @@ change the original ``Categorical``:
 
 .. ipython:: python
 
-    cat = pd.Categorical([1,2,3,10], categories=[1,2,3,4,10])
+    cat = pd.Categorical([1, 2, 3, 10], categories=[1, 2, 3, 4, 10])
     s = pd.Series(cat, name="cat")
     cat
     s.iloc[0:2] = 10
     cat
     df = pd.DataFrame(s)
-    df["cat"].cat.categories = [1,2,3,4,5]
+    df["cat"].cat.categories = [1, 2, 3, 4, 5]
     cat
 
 Use ``copy=True`` to prevent such a behaviour or simply don't reuse ``Categoricals``:
 
 .. ipython:: python
 
-    cat = pd.Categorical([1,2,3,10], categories=[1,2,3,4,10])
+    cat = pd.Categorical([1, 2, 3, 10], categories=[1, 2, 3, 4, 10])
     s = pd.Series(cat, name="cat", copy=True)
     cat
     s.iloc[0:2] = 10


Code review comments:
diff_hunk: @@ -7,6 +7,9 @@
 
    import numpy as np
    import pandas as pd
+   from pandas.api.types import CategoricalDtype
path: doc/source/categorical.rst
text: @user1:
I think these imports are better served where they were before. These aren't part of the top level API so no need to hide

@user2:
Agree, I think `flake8-rst` is reporting as errors having these imports in the blocks, but that should be ignored in the config: https://github.com/pandas-dev/pandas/pull/23802#issuecomment-440319546

@author:
oh, i see, thanks!!

diff_hunk: @@ -1126,12 +1138,12 @@ are not numeric data (even in the case that ``.categories`` is numeric).
 
 .. ipython:: python
 
-    s = pd.Series(pd.Categorical([1,2,3,4]))
+    s = pd.Series(pd.Categorical([1, 2, 3, 4]))
     try:
         np.sum(s)
-        #same with np.log(s),..
+        # same with np.log(s),..
     except TypeError as e:
-         print("TypeError: " + str(e))
+        print("TypeError: " + str(e))
path: doc/source/categorical.rst
text: @user1:
```suggestion
        print("TypeError:", str(e))
```

@author:
thanks, changed this and applied the same to others.