Moved format documentation from code to docs (#420)

3 files changed, 187 insertions, 193 deletions

diff --git a/docs/formats.rst b/docs/formats.rst
new file mode 100644
index 0000000..6dac434
--- /dev/null
+++ b/docs/formats.rst
@@ -0,0 +1,182 @@
+.. _formats:
+
+=======
+Formats
+=======
+
+Tablib supports a wide variety of different tabular formats, both for input and
+output. Moreover, you can :ref:`register your own formats <newformats>`.
+
+csv
+===
+
+When you import CSV data, you can specify if the first line of your data source
+is headers with the ``headers`` boolean parameter (defaults to ``True``)::
+
+    import tablib
+
+    tablib.import_set(your_data_stream, format='csv', headers=False)
+
+When exporting with the ``csv`` format, the top row will contain headers, if
+they have been set. Otherwise, the top row will contain the first row of the
+dataset.
+
+.. admonition:: Line endings
+
+     Exporting uses \\r\\n line endings by default so, make sure to include
+     ``newline=''`` otherwise you will get a blank line between each row
+     when you open the file in Excel::
+
+         with open('output.csv', 'w', newline='') as f:
+             f.write(dataset.export('csv'))
+
+     If you do not do this, and you export the file on Windows, your
+     CSV file will open in Excel with a blank line between each row.
+
+dbf
+===
+
+Import/export using the dBASE_ format.
+
+.. admonition:: Binary Warning
+
+    The ``dbf`` format contains binary data, so make sure to write in binary
+    mode::
+
+        with open('output.dbf', 'wb') as f:
+            f.write(dataset.export('dbf')
+
+.. _dBASE: https://en.wikipedia.org/wiki/DBase
+
+df (DataFrame)
+==============
+
+Import/export using the pandas_ DataFrame format.
+
+.. _pandas: https://pandas.pydata.org/
+
+html
+====
+
+The ``html`` format is currently export-only. The exports produce an HTML page
+with the data in a ``<table>``. If headers have been set, they will be used as
+table headers.
+
+jira
+====
+
+The ``jira`` format is currently export-only. Exports format the dataset
+according to the Jira table syntax::
+
+    ||heading 1||heading 2||heading 3||
+    |col A1|col A2|col A3|
+    |col B1|col B2|col B3|
+
+json
+====
+
+Import/export using the JSON_ format. If headers have been set, a JSON list of
+objects will be returned. If no headers have been set, a JSON list of lists
+(rows) will be returned instead.
+
+Import assumes (for now) that headers exist.
+
+.. _JSON: http://json.org/
+
+latex
+=====
+
+Import/export using the LaTeX_ format. This format is export-only.
+If a title has been set, it will be exported as the table caption.
+ 
+.. _LaTeX: https://www.latex-project.org/
+
+ods
+===
+
+Export data in OpenDocument Spreadsheet format. The ``ods`` format is currently
+export-only.
+
+.. admonition:: Binary Warning
+
+    :class:`Dataset.ods` contains binary data, so make sure to write in binary mode::
+
+        with open('output.ods', 'wb') as f:
+            f.write(data.ods)
+
+rst
+===
+
+Export data as a reStructuredText_ table representation of a dataset. The
+``rst`` format is export-only.
+
+Exporting returns a simple table if the text in the first column is never
+wrapped, otherwise returns a grid table::
+
+    >>> from tablib import Dataset
+    >>> bits = ((0, 0), (1, 0), (0, 1), (1, 1))
+    >>> data = Dataset()
+    >>> data.headers = ['A', 'B', 'A and B']
+    >>> for a, b in bits:
+    ...     data.append([bool(a), bool(b), bool(a * b)])
+    >>> table = data.export('rst')
+    >>> table.split('\\n') == [
+    ...     '=====  =====  =====',
+    ...     '  A      B    A and',
+    ...     '                B  ',
+    ...     '=====  =====  =====',
+    ...     'False  False  False',
+    ...     'True   False  False',
+    ...     'False  True   False',
+    ...     'True   True   True ',
+    ...     '=====  =====  =====',
+    ... ]
+    True
+
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+
+tsv
+===
+
+A variant of the csv_ format with tabulators as fields separators.
+
+xls
+===
+
+Import/export data in Legacy Excel Spreadsheet representation.
+
+.. note::
+
+    XLS files are limited to a maximum of 65,000 rows. Use xlsx_ to avoid this
+    limitation.
+
+.. admonition:: Binary Warning
+
+    The `xls` file format is binary, so make sure to write in binary mode::
+
+        with open('output.xls', 'wb') as f:
+            f.write(data.export('xls'))
+
+xlsx
+====
+
+Import/export data in Excel 07+ Spreadsheet representation.
+
+.. admonition:: Binary Warning
+
+    The `xlsx` file format is binary, so make sure to write in binary mode::
+
+        with open('output.xlsx', 'wb') as f:
+            f.write(data.export('xlsx'))
+
+yaml
+====
+
+Import/export data in the YAML_ format.
+When exporting, if headers have been set, a YAML list of objects will be
+returned. If no headers have been set, a YAML list of lists (rows) will be
+returned instead.
+
+Import assumes (for now) that headers exist.
+
+.. _YAML: https://yaml.org
diff --git a/docs/index.rst b/docs/index.rst
index 60d0c55..44b2712 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -101,6 +101,11 @@ This part of the documentation, which is mostly prose, begins with some backgrou
 .. toctree::
    :maxdepth: 2
 
+   formats
+
+.. toctree::
+   :maxdepth: 2
+
    development
 
 
diff --git a/src/tablib/core.py b/src/tablib/core.py
index a5ea0b0..d17e1e8 100644
--- a/src/tablib/core.py
+++ b/src/tablib/core.py
@@ -424,199 +424,6 @@ class Dataset:
 
         return fmt.export_set(self, **kwargs)
 
-    # -------
-    # Formats
-    # -------
-
-    @property
-    def xls():
-        """A Legacy Excel Spreadsheet representation of the :class:`Dataset` object, with :ref:`separators`. Cannot be set.
-
-        .. note::
-
-            XLS files are limited to a maximum of 65,000 rows. Use :class:`Dataset.xlsx` to avoid this limitation.
-
-         .. admonition:: Binary Warning
-
-             :class:`Dataset.xls` contains binary data, so make sure to write in binary mode::
-
-                with open('output.xls', 'wb') as f:
-                    f.write(data.xls)
-        """
-        pass
-
-    @property
-    def xlsx():
-        """An Excel '07+ Spreadsheet representation of the :class:`Dataset` object, with :ref:`separators`. Cannot be set.
-
-         .. admonition:: Binary Warning
-
-             :class:`Dataset.xlsx` contains binary data, so make sure to write in binary mode::
-
-                with open('output.xlsx', 'wb') as f:
-                    f.write(data.xlsx)
-        """
-        pass
-
-    @property
-    def ods():
-        """An OpenDocument Spreadsheet representation of the :class:`Dataset` object, with :ref:`separators`. Cannot be set.
-
-         .. admonition:: Binary Warning
-
-             :class:`Dataset.ods` contains binary data, so make sure to write in binary mode::
-
-                with open('output.ods', 'wb') as f:
-                    f.write(data.ods)
-        """
-        pass
-
-    @property
-    def csv():
-        """A CSV representation of the :class:`Dataset` object. The top row will contain
-        headers, if they have been set. Otherwise, the top row will contain
-        the first row of the dataset.
-
-        A dataset object can also be imported by setting the :class:`Dataset.csv` attribute. ::
-
-            data = tablib.Dataset()
-            data.csv = 'age, first_name, last_name\\n90, John, Adams'
-
-        Import assumes (for now) that headers exist.
-
-        .. admonition:: Binary Warning for Python 2
-
-             :class:`Dataset.csv` uses \\r\\n line endings by default so, in Python 2, make
-             sure to write in binary mode::
-
-                 with open('output.csv', 'wb') as f:
-                     f.write(data.csv)
-
-             If you do not do this, and you export the file on Windows, your
-             CSV file will open in Excel with a blank line between each row.
-
-        .. admonition:: Line endings for Python 3
-
-             :class:`Dataset.csv` uses \\r\\n line endings by default so, in Python 3, make
-             sure to include newline='' otherwise you will get a blank line between each row
-             when you open the file in Excel::
-
-                 with open('output.csv', 'w', newline='') as f:
-                     f.write(data.csv)
-
-             If you do not do this, and you export the file on Windows, your
-             CSV file will open in Excel with a blank line between each row.
-        """
-        pass
-
-    @property
-    def tsv():
-        """A TSV representation of the :class:`Dataset` object. The top row will contain
-        headers, if they have been set. Otherwise, the top row will contain
-        the first row of the dataset.
-
-        A dataset object can also be imported by setting the :class:`Dataset.tsv` attribute. ::
-
-            data = tablib.Dataset()
-            data.tsv = 'age\tfirst_name\tlast_name\\n90\tJohn\tAdams'
-
-        Import assumes (for now) that headers exist.
-        """
-        pass
-
-    @property
-    def yaml():
-        """A YAML representation of the :class:`Dataset` object. If headers have been
-        set, a YAML list of objects will be returned. If no headers have
-        been set, a YAML list of lists (rows) will be returned instead.
-
-        A dataset object can also be imported by setting the :class:`Dataset.yaml` attribute: ::
-
-            data = tablib.Dataset()
-            data.yaml = '- {age: 90, first_name: John, last_name: Adams}'
-
-        Import assumes (for now) that headers exist.
-        """
-        pass
-
-    @property
-    def df():
-        """A DataFrame representation of the :class:`Dataset` object.
-
-        A dataset object can also be imported by setting the :class:`Dataset.df` attribute: ::
-
-            data = tablib.Dataset()
-            data.df = DataFrame(np.random.randn(6,4))
-
-        Import assumes (for now) that headers exist.
-        """
-        pass
-
-    @property
-    def json():
-        """A JSON representation of the :class:`Dataset` object. If headers have been
-        set, a JSON list of objects will be returned. If no headers have
-        been set, a JSON list of lists (rows) will be returned instead.
-
-        A dataset object can also be imported by setting the :class:`Dataset.json` attribute: ::
-
-            data = tablib.Dataset()
-            data.json = '[{"age": 90, "first_name": "John", "last_name": "Adams"}]'
-
-        Import assumes (for now) that headers exist.
-        """
-        pass
-
-    @property
-    def html():
-        """A HTML table representation of the :class:`Dataset` object. If
-        headers have been set, they will be used as table headers.
-
-        .. notice:: This method can be used for export only.
-        """
-        pass
-
-    @property
-    def dbf():
-        """A dBASE representation of the :class:`Dataset` object.
-
-        A dataset object can also be imported by setting the
-        :class:`Dataset.dbf` attribute. ::
-
-            # To import data from an existing DBF file:
-            data = tablib.Dataset()
-            data.dbf = open('existing_table.dbf', mode='rb').read()
-
-            # to import data from an ASCII-encoded bytestring:
-            data = tablib.Dataset()
-            data.dbf = '<bytestring of tabular data>'
-
-        .. admonition:: Binary Warning
-
-            :class:`Dataset.dbf` contains binary data, so make sure to write in binary mode::
-
-                with open('output.dbf', 'wb') as f:
-                    f.write(data.dbf)
-        """
-        pass
-
-    @property
-    def latex():
-        """A LaTeX booktabs representation of the :class:`Dataset` object. If a
-        title has been set, it will be exported as the table caption.
-
-        .. note:: This method can be used for export only.
-        """
-        pass
-
-    @property
-    def jira():
-        """A Jira table representation of the :class:`Dataset` object.
-
-        .. note:: This method can be used for export only.
-        """
-        pass
-
     # ----
     # Rows
     # ----