diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 7785f5fe3283d..f3c9239fb58e7 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -303,6 +303,13 @@ Some other important things to know about the docs: output saved) during the doc build. This way, they will always be up to date, but it makes the doc building a bit more complex. +- The utility script ``scripts/api_rst_coverage.py`` can be used to compare + the list of methods documented in ``doc/source/api.rst`` (which is used to generate + the `API Reference `_ page) + and the actual methods of the classes ``Series``, ``DataFrame``, ``Panel``, and ``Panel4D``. + It will identify methods documented in in ``doc/source/api.rst`` that are not actually + class methods, and class methods that are not documented in ``doc/source/api.rst``. + How to build the pandas documentation ------------------------------------- diff --git a/scripts/api_rst_coverage.py b/scripts/api_rst_coverage.py new file mode 100644 index 0000000000000..cc456f03c02ec --- /dev/null +++ b/scripts/api_rst_coverage.py @@ -0,0 +1,43 @@ +import pandas as pd +import inspect +import re + +def main(): + # classes whose members to check + classes = [pd.Series, pd.DataFrame, pd.Panel, pd.Panel4D] + + def class_name_sort_key(x): + if x.startswith('Series'): + # make sure Series precedes DataFrame, Panel, and Panel4D + return ' ' + x + else: + return x + + # class members + class_members = set() + for cls in classes: + class_members.update([cls.__name__ + '.' + x[0] for x in inspect.getmembers(cls)]) + + # class members referenced in api.rst + api_rst_members = set() + file_name = '../doc/source/api.rst' + with open(file_name, 'r') as f: + pattern = re.compile('({})\.(\w+)'.format('|'.join([cls.__name__ for cls in classes]))) + for line in f: + match = pattern.search(line) + if match: + api_rst_members.add(match.group(0)) + + print() + print("Documented members in api.rst that aren't actual class members:") + for x in sorted(api_rst_members.difference(class_members), key=class_name_sort_key): + print(x) + + print() + print("Class members (other than those beginning with '_') missing from api.rst:") + for x in sorted(class_members.difference(api_rst_members), key=class_name_sort_key): + if '._' not in x: + print(x) + +if __name__ == "__main__": + main()