From cf40991093e746e5dde40fca4f322ecfc3dfff78 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Sat, 26 Sep 2015 12:29:56 +0200 Subject: [PATCH 1/3] DOC: hack to numpydoc to avoid warnings for Categorical (not including members) The Categorical docstring in api.rst uses a seperate template to not include an autosummary table with toctrees of all members. But numpydoc still includes a list by default (which will gives thousands of warnings). This hack ensures that for Categorical class docstring this list is not included. --- doc/sphinxext/numpydoc/docscrape_sphinx.py | 3 ++- doc/sphinxext/numpydoc/numpydoc.py | 4 ++++ 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/doc/sphinxext/numpydoc/docscrape_sphinx.py b/doc/sphinxext/numpydoc/docscrape_sphinx.py index ba93b2eab779d..b103da80a8d23 100755 --- a/doc/sphinxext/numpydoc/docscrape_sphinx.py +++ b/doc/sphinxext/numpydoc/docscrape_sphinx.py @@ -19,6 +19,7 @@ def __init__(self, docstring, config={}): def load_config(self, config): self.use_plots = config.get('use_plots', False) self.class_members_toctree = config.get('class_members_toctree', True) + self.class_members_list = config.get('class_members_list', True) # string conversion routines def _str_header(self, name, symbol='`'): @@ -95,7 +96,7 @@ def _str_member_list(self, name): """ out = [] - if self[name]: + if self[name] and self.class_members_list: out += ['.. rubric:: %s' % name, ''] prefix = getattr(self, '_name', '') diff --git a/doc/sphinxext/numpydoc/numpydoc.py b/doc/sphinxext/numpydoc/numpydoc.py index 2bc2d1e91ed3f..0cccf72de3745 100755 --- a/doc/sphinxext/numpydoc/numpydoc.py +++ b/doc/sphinxext/numpydoc/numpydoc.py @@ -42,6 +42,10 @@ def mangle_docstrings(app, what, name, obj, options, lines, class_members_toctree=app.config.numpydoc_class_members_toctree, ) + # PANDAS HACK (to remove the list of methods/attributes for Categorical) + if what == "class" and name.endswith(".Categorical"): + cfg['class_members_list'] = False + if what == 'module': # Strip top title title_re = re.compile(sixu('^\\s*[#*=]{4,}\\n[a-z0-9 -]+\\n[#*=]{4,}\\s*'), From 32ace135c249f9ac67fb5f78ae5c748a17902669 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Sat, 26 Sep 2015 13:01:12 +0200 Subject: [PATCH 2/3] DOC: add str accessor docstring pages to api.rst to avoid warning --- doc/source/api.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/source/api.rst b/doc/source/api.rst index b1c7b569c0c42..bfd1c92d14acd 100644 --- a/doc/source/api.rst +++ b/doc/source/api.rst @@ -611,7 +611,7 @@ strings and apply several methods to it. These can be acccessed like .. The following is needed to ensure the generated pages are created with the - correct template (otherwise they would be created in the Series class page) + correct template (otherwise they would be created in the Series/Index class page) .. .. autosummary:: @@ -621,6 +621,10 @@ strings and apply several methods to it. These can be acccessed like Series.str Series.cat Series.dt + Index.str + CategoricalIndex.str + DatetimeIndex.str + TimedeltaIndex.str .. _api.categorical: From 70c9d318ed4ef32e1c294a4dbefcb783cda19dba Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Sat, 26 Sep 2015 14:23:11 +0200 Subject: [PATCH 3/3] DOC: hack to numpydoc to include attributes that are None (GH6100) See GH6100. Some attributes of our classes are None, even on the class objects themselves (so not on instances). By default, numpydoc does not include them in the autosummary table but in a separate plain table. But, our class.rst template does include them in the toctree autosummary, which creates docstring pages for these. This results in warnings "WARNING: document isn't included in any toctree". This hack to numpydoc does include them in the autosummary in the class docstring, removing this warning. --- doc/sphinxext/numpydoc/docscrape_sphinx.py | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/doc/sphinxext/numpydoc/docscrape_sphinx.py b/doc/sphinxext/numpydoc/docscrape_sphinx.py index b103da80a8d23..5a582b4d03282 100755 --- a/doc/sphinxext/numpydoc/docscrape_sphinx.py +++ b/doc/sphinxext/numpydoc/docscrape_sphinx.py @@ -115,11 +115,13 @@ def _str_member_list(self, name): or inspect.isgetsetdescriptor(param_obj)): param_obj = None - if param_obj and (pydoc.getdoc(param_obj) or not desc): - # Referenced object has a docstring - autosum += [" %s%s" % (prefix, param)] - else: - others.append((param, param_type, desc)) + # pandas HACK - do not exclude attributes wich are None + # if param_obj and (pydoc.getdoc(param_obj) or not desc): + # # Referenced object has a docstring + # autosum += [" %s%s" % (prefix, param)] + # else: + # others.append((param, param_type, desc)) + autosum += [" %s%s" % (prefix, param)] if autosum: out += ['.. autosummary::']