Adding tests to the function that parses api.rst

pandas-dev · datapythonista · Oct 13, 2018 · Aug 18, 2018 · Aug 18, 2018 · Aug 18, 2018
commit 1d2c5c0422e1e98d1635a3717a101a313e89b868
diff --git a/scripts/tests/test_validate_docstrings.py b/scripts/tests/test_validate_docstrings.py
@@ -1,5 +1,6 @@
 import string
 import random
+import io
 import pytest
 import numpy as np
 
@@ -605,3 +606,79 @@ def test_bad_examples(self, capsys, klass, func, msgs):
         result = validate_one(self._import_path(klass=klass, func=func))  # noqa:F821
         for msg in msgs:
             assert msg in ' '.join(result['errors'])
+
+
+class TestApiItems(object):
+    @property
+    def api_doc(self):
+        return io.StringIO('''
+.. currentmodule:: itertools
+
+Itertools
+---------
+
+Infinite
+~~~~~~~~
+
+.. autosummary::
+
+    cycle
+    count
+
+Finite
+~~~~~~
+
+.. autosummary::
+
+    chain
+
+.. currentmodule:: random
+
+Random
+------
+
+All
+~~~
+
+.. autosummary::
+
+    seed
+    randint
+''')
+
+    @pytest.mark.parametrize('idx,name', [(0, 'itertools.cycle'),
+                                          (1, 'itertools.count'),
+                                          (2, 'itertools.chain'),
+                                          (3, 'random.seed'),
+                                          (4, 'random.randint')])
+    def test_item_name(self, idx, name):
+        res = list(validate_docstrings.get_api_items(self.api_doc))
+        assert res[idx][0] == name
+
+    @pytest.mark.parametrize('idx,func', [(0, 'cycle'),
+                                          (1, 'count'),
+                                          (2, 'chain'),
+                                          (3, 'seed'),
+                                          (4, 'randint')])
+    def test_item_function(self, idx, func):
+        res = list(validate_docstrings.get_api_items(self.api_doc))
+        assert callable(res[idx][1])
+        assert res[idx][1].__name__ == func
+
+    @pytest.mark.parametrize('idx,section', [(0, 'Itertools'),
+                                             (1, 'Itertools'),
+                                             (2, 'Itertools'),
+                                             (3, 'Random'),
+                                             (4, 'Random')])
+    def test_item_section(self, idx, section):
+        res = list(validate_docstrings.get_api_items(self.api_doc))
+        assert res[idx][2] == section
+
+    @pytest.mark.parametrize('idx,subsection', [(0, 'Infinite'),
+                                                (1, 'Infinite'),
+                                                (2, 'Finite'),
+                                                (3, 'All'),
+                                                (4, 'All')])
+    def test_item_subsection(self, idx, subsection):
+        res = list(validate_docstrings.get_api_items(self.api_doc))
+        assert res[idx][3] == subsection
diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py
@@ -45,11 +45,17 @@
 DIRECTIVES = ['versionadded', 'versionchanged', 'deprecated']
 
 
-def get_api_items():
+def get_api_items(api_doc_fd):
    """
     Parse api.rst file from the documentation, and extract all the functions,
     methods, classes, attributes... This should include all pandas public API.
 
+    Parameters
+    ----------
+    api_doc_fd : file descriptor
+        A file descriptor of the API documentation page, containing the table
+        of contents with all the public API.
+
     Yields
     ------
     name : str
@@ -64,47 +70,44 @@ def get_api_items():
         The name of the subsection in the API page where the object item is
         located.
     """
-    api_fname = os.path.join(BASE_PATH, 'doc', 'source', 'api.rst')
-
     previous_line = current_section = current_subsection = ''
     position = None
-    with open(api_fname) as f:
-        for line in f:
-            line = line.strip()
-            if len(line) == len(previous_line):
-                if set(line) == set('-'):
-                    current_section = previous_line
-                    continue
-                if set(line) == set('~'):
-                    current_subsection = previous_line
-                    continue
-
-            if line.startswith('.. currentmodule::'):
-                current_module = line.replace('.. currentmodule::', '').strip()
+    for line in api_doc_fd:
+        line = line.strip()
+        if len(line) == len(previous_line):
+            if set(line) == set('-'):
+                current_section = previous_line
                 continue
-
-            if line == '.. autosummary::':
-                position = 'autosummary'
+            if set(line) == set('~'):
+                current_subsection = previous_line
                 continue
 
-            if position == 'autosummary':
-                if line == '':
-                    position = 'items'
-                    continue
+        if line.startswith('.. currentmodule::'):
+            current_module = line.replace('.. currentmodule::', '').strip()
+            continue
 
-            if position == 'items':
-                if line == '':
-                    position = None
-                    continue
-                item = line.strip()
-                func = importlib.import_module(current_module)
-                for part in item.split('.'):
-                    func = getattr(func, part)
+        if line == '.. autosummary::':
+            position = 'autosummary'
+            continue
+
+        if position == 'autosummary':
+            if line == '':
+                position = 'items'
+                continue
+
+        if position == 'items':
+            if line == '':
+                position = None
+                continue
+            item = line.strip()
+            func = importlib.import_module(current_module)
+            for part in item.split('.'):
+                func = getattr(func, part)
 
-                yield ('.'.join([current_module, item]), func,
-                       current_section, current_subsection)
+            yield ('.'.join([current_module, item]), func,
+                   current_section, current_subsection)
 
-            previous_line = line
+        previous_line = line
 
 
 class Docstring(object):
@@ -534,7 +537,9 @@ def validate_all():
     seen = {}
 
     # functions from the API docs
-    api_items = list(get_api_items())
+    api_doc_fname = os.path.join(BASE_PATH, 'doc', 'source', 'api.rst')
+    with open(api_doc_fname) as f:
+        api_items = list(get_api_items(f))
     for func_name, func_obj, section, subsection in api_items:
         doc_info = validate_one(func_name)
         result[func_name] = doc_info