DOC: clean up io docs and fix up links

[cpcloud]

closes #3718.

[jreback]

i just merged #3693, prob need to rebase this (some docs changed a bit)

[cpcloud]

rebased

[jreback]

fyi...i just pushed a change to fix a couple of doc building issues, but a few remain, I think having to do with the formatting of the doc strings.....they are basically indentation error in to_csv,lookup,replace....can you take a look if you have a chance?

[cpcloud]

arg i'm a little annoyed that there are doc building issues with my replace docstring. i spent a lot of time trying to make sure that didn't happen! evidently not enough :(

[cpcloud]

@jreback i just looked at to_csv lookup and replace and they all seem to be in order. what error(s) are you getting?

[jreback]

fyi...first delete pandas/doc/generated

I think you may only get this on a complete rebuild

see the warnings about 1/2 down

[goat-jreback-~/pandas/doc] python make.py html
Running Sphinx v1.1.3
loading pickled environment... done
[autosummary] generating autosummary for: 10min.rst, api.rst, basics.rst, comparison_with_r.rst, computation.rst, cookbook.rst, dsintro.rst, faq.rst, gotchas.rst, groupby.rst, ..., missing_data.rst, overview.rst, r_interface.rst, related.rst, reshaping.rst, rplot.rst, sparse.rst, timeseries.rst, visualization.rst, whatsnew.rst
[autosummary] generating autosummary for: /mnt/home/jreback/pandas/doc/source/generated/pandas.DataFrame.T.rst, /mnt/home/jreback/pandas/doc/source/generated/pandas.DataFrame.__init__.rst, /mnt/home/jreback/pandas/doc/source/generated/pandas.DataFrame.__iter__.rst, /mnt/home/jreback/pandas/doc/source/generated/pandas.DataFrame.abs.rst, /mnt/home/jreback/pandas/doc/source/generated/pandas.DataFrame.add.rst, /mnt/home/jreback/pandas/doc/source/generated/pandas.DataFrame.add_prefix.rst, /mnt/home/jreback/pandas/doc/source/generated/pandas.DataFrame.add_suffix.rst, /mnt/home/jreback/pandas/doc/source/generated/pandas.DataFrame.align.rst, /mnt/home/jreback/pandas/doc/source/generated/pandas.DataFrame.any.rst, /mnt/home/jreback/pandas/doc/source/generated/pandas.DataFrame.append.rst, ..., /mnt/home/jreback/pandas/doc/source/generated/pandas.stats.moments.rolling_mean.rst, /mnt/home/jreback/pandas/doc/source/generated/pandas.stats.moments.rolling_median.rst, /mnt/home/jreback/pandas/doc/source/generated/pandas.stats.moments.rolling_quantile.rst, /mnt/home/jreback/pandas/doc/source/generated/pandas.stats.moments.rolling_skew.rst, /mnt/home/jreback/pandas/doc/source/generated/pandas.stats.moments.rolling_std.rst, /mnt/home/jreback/pandas/doc/source/generated/pandas.stats.moments.rolling_sum.rst, /mnt/home/jreback/pandas/doc/source/generated/pandas.stats.moments.rolling_var.rst, /mnt/home/jreback/pandas/doc/source/generated/pandas.tools.merge.concat.rst, /mnt/home/jreback/pandas/doc/source/generated/pandas.tools.merge.merge.rst, /mnt/home/jreback/pandas/doc/source/generated/pandas.tools.pivot.pivot_table.rst
building [html]: targets for 363 source files that are out of date
updating environment: 1 added, 364 changed, 1 removed
/mnt/home/jreback/pandas/doc/sphinxext/docscrape.py:117: UserWarning: Unknown section Optional Parameters                                                                                                                                                           
  warn("Unknown section %s" % key)
/mnt/home/jreback/pandas/doc/sphinxext/docscrape.py:117: UserWarning: Unknown section Example
  warn("Unknown section %s" % key)
/usr/local/lib/python2.7/site-packages/matplotlib/font_manager.py:1214: UserWarning: findfont: Font family ['monospace'] not found. Falling back to Bitstream Vera Sans                                                                                             
  (prop.get_family(), self.defaultFamily[fontext]))

[u'DataFrame.lookup(row_labels, col_labels)', u':module: pandas', u'', u'', u'', u'Label-based "fancy indexing" function for DataFrame. Given equal-length', u'arrays of row and column labels, return an array of the values', u'corresponding to each (row, col)  pair.', u'', u'', u':Parameters:', u'', u'    **row_labels** : sequence', u'', u'        ', u'', u'    **col_labels** : sequence', u'', u'        ', u'', u'.. rubric:: Notes', u'', u'', u'Akin to', u'', u'result = []', u'for row, col in zip(row_labels, col_labels):', u'    result.append(df.get_value(row, col))']:19: ERROR: Unexpected indentation.
/home/jreback/pandas/pandas/core/frame.py:docstring of pandas.DataFrame.replace:38: WARNING: Bullet list ends without a blank line; unexpected unindent.
/home/jreback/pandas/pandas/core/frame.py:docstring of pandas.DataFrame.to_csv:12: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/jreback/pandas/pandas/core/frame.py:docstring of pandas.DataFrame.to_csv:31: WARNING: Definition list ends without a blank line; unexpected unindent.
[u"DataFrame.to_csv(path_or_buf, sep=',', na_rep='', float_format=None, cols=None, header=True, index=True, index_label=None, mode='w', nanRep=None, encoding=None, quoting=None, line_terminator='\\n', chunksize=None, tupleize_cols=True, **kwds)", u':module: pandas', u'', u'', u'', u'Write DataFrame to a comma-separated values (csv) file', u'', u'', u':Parameters:', u'', u'    **path_or_buf** : string or file handle / StringIO', u'', u'            File path', u'        sep : character, default ","', u'            Field delimiter for the output file.', u"        na_rep : string, default ''", u'            Missing data representation', u'        float_format : string, default None', u'            Format string for floating point numbers', u'        cols : sequence, optional', u'            Columns to write', u'        header : boolean or list of string, default True', u'            Write out column names. If a list of string is given it is', u'            assumed to be aliases for the column names', u'        index : boolean, default True', u'            Write row names (index)', u'        index_label : string or sequence, or False, default None', u'            Column label for index column(s) if desired. If None is given, and', u'            `header` and `index` are True, then the index names are used. A', u'            sequence should be given if the DataFrame uses MultiIndex.  If', u'            False do not print fields for index names. Use index_label=False', u'            for easier importing in R', u'        nanRep : deprecated, use na_rep', u"        mode : Python write mode, default 'w'", u'        encoding : string, optional', u'            a string representing the encoding to use if the contents are', u'            non-ascii, for python versions prior to 3', u"        line_terminator: string, default '", u'', u"    **'** : ", u'', u'            The newline character or character sequence to use in the output', u'            file', u'        quoting : optional constant from csv module', u'            defaults to csv.QUOTE_MINIMAL', u'        chunksize : rows to write at a time', u'        tupleize_cols : boolean, default True', u'            write multi_index columns as a list of tuples (if True)', u'            or new (expanded format) if False)']:32: ERROR: Unexpected indentation.
/home/jreback/pandas/pandas/core/frame.py:docstring of pandas.DataFrame.to_csv:36: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/jreback/pandas/pandas/core/frame.py:docstring of pandas.DataFrame.to_csv:42: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/jreback/pandas/pandas/core/frame.py:docstring of pandas.DataFrame.to_csv:44: WARNING: Definition list ends without a blank line; unexpected unindent.
[u"DataFrame.to_csv(path_or_buf, sep=',', na_rep='', float_format=None, cols=None, header=True, index=True, index_label=None, mode='w', nanRep=None, encoding=None, quoting=None, line_terminator='\\n', chunksize=None, tupleize_cols=True, **kwds)", u':module: pandas', u'', u'', u'', u'Write DataFrame to a comma-separated values (csv) file', u'', u'', u':Parameters:', u'', u'    **path_or_buf** : string or file handle / StringIO', u'', u'            File path', u'        sep : character, default ","', u'            Field delimiter for the output file.', u"        na_rep : string, default ''", u'            Missing data representation', u'        float_format : string, default None', u'            Format string for floating point numbers', u'        cols : sequence, optional', u'            Columns to write', u'        header : boolean or list of string, default True', u'            Write out column names. If a list of string is given it is', u'            assumed to be aliases for the column names', u'        index : boolean, default True', u'            Write row names (index)', u'        index_label : string or sequence, or False, default None', u'            Column label for index column(s) if desired. If None is given, and', u'            `header` and `index` are True, then the index names are used. A', u'            sequence should be given if the DataFrame uses MultiIndex.  If', u'            False do not print fields for index names. Use index_label=False', u'            for easier importing in R', u'        nanRep : deprecated, use na_rep', u"        mode : Python write mode, default 'w'", u'        encoding : string, optional', u'            a string representing the encoding to use if the contents are', u'            non-ascii, for python versions prior to 3', u"        line_terminator: string, default '", u'', u"    **'** : ", u'', u'            The newline character or character sequence to use in the output', u'            file', u'        quoting : optional constant from csv module', u'            defaults to csv.QUOTE_MINIMAL', u'        chunksize : rows to write at a time', u'        tupleize_cols : boolean, default True', u'            write multi_index columns as a list of tuples (if True)', u'            or new (expanded format) if False)']:44: ERROR: Unexpected indentation.
[u'ExcelFile.parse(sheetname, header=0, skiprows=None, skip_footer=0, index_col=None, parse_cols=None, parse_dates=False, date_parser=None, na_values=None, thousands=None, chunksize=None, **kwds)', u':module: pandas.io.excel', u'', u'', u'', u'Read Excel table into DataFrame', u'', u'', u':Parameters:', u'', u'    **sheetname** : string', u'', u'        Name of Excel sheet', u'', u'    **header** : int, default 0', u'', u'        Row to use for the column labels of the parsed DataFrame', u'', u'    **skiprows** : list-like', u'', u'        Rows to skip at the beginning (0-indexed)', u'', u'    **skip_footer** : int, default 0', u'', u'        Rows at the end to skip (0-indexed)', u'', u'    **index_col** : int, default None', u'', u'        Column to use as the row labels of the DataFrame. Pass None if', u'        there is no such column', u'', u'    **parse_cols** : int or list, default None', u'', u'        If None then parse all columns,', u'        If int then indicates last column to be parsed', u'        If list of ints then indicates list of column numbers to be parsed', u'        If string then indicates comma separated list of column names and', u'            column ranges (e.g. "A:E" or "A,C,E:F")', u'', u'    **na_values** : list-like, default None', u'', u'        List of additional strings to recognize as NA/NaN', u'', u':Returns:', u'', u'    **parsed** : DataFrame']:34: ERROR: Unexpected indentation.
[u'read_excel(path_or_buf, sheetname, header=0, skiprows=None, skip_footer=0, index_col=None, parse_cols=None, parse_dates=False, date_parser=None, na_values=None, thousands=None, chunksize=None, kind=None, **kwds)', u':module: pandas.io.excel', u'', u'', u'', u'Read Excel table into DataFrame', u'', u'', u':Parameters:', u'', u'    **sheetname** : string', u'', u'        Name of Excel sheet', u'', u'    **header** : int, default 0', u'', u'        Row to use for the column labels of the parsed DataFrame', u'', u'    **skiprows** : list-like', u'', u'        Rows to skip at the beginning (0-indexed)', u'', u'    **skip_footer** : int, default 0', u'', u'        Rows at the end to skip (0-indexed)', u'', u'    **index_col** : int, default None', u'', u'        Column to use as the row labels of the DataFrame. Pass None if', u'        there is no such column', u'', u'    **parse_cols** : int or list, default None', u'', u'        If None then parse all columns,', u'        If int then indicates last column to be parsed', u'        If list of ints then indicates list of column numbers to be parsed', u'        If string then indicates comma separated list of column names and', u'            column ranges (e.g. "A:E" or "A,C,E:F")', u'', u'    **na_values** : list-like, default None', u'', u'        List of additional strings to recognize as NA/NaN', u'', u':Returns:', u'', u'    **parsed** : DataFrame']:34: ERROR: Unexpected indentation.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done

[cpcloud]

@jreback there are also intermittent spurious warnings about the lack of scikits.timeseries...

[cpcloud]

ah silly me sphinx has line break rules about nested lists

[jreback]

you prob don't have scikit.timeseries installed (its only used in an example section anyhow)

[cpcloud]

yep i def don't and i've ignored the warnings , but now i might just installed so that sphinx will stfu

[cpcloud]

these sphinx bugs WILL be squashed!!

• lookup (sphinx doesn't like when parameters are list with no explanation) kind of a good thing if you ask me since if you don't like errors write a frickin' explanation