Refactoring document

.gitignore

@@ -0,0 +1 @@
+*.swp

csv-table.rst

@@ -0,0 +1,31 @@
+Long tables
+===========
+
+You might be dealing with a large table, one that would be difficult to write as a `regular table <regular-table.html>`_ described before. 
+
+One possibility is to use CSV files. You can store your data in a CSV table, without the need to worry about misplacing an equal sign in your table. 
+
+If your table is really long, however, it might sometimes break in the PDF output. Take for example the table below. 
+
+In order to make it look good in the PDF, you should use some LaTeX magic, disguised in RST directives. Using the :code:`:class: longtable` parameter in the table definition allows to nicely break long tables into several pages. You can also control the width of the individual columns with the :code:`tabularcolumns` directive: this will be familiar to you if you used LaTeX before. 
+
+Finally, the :code:`:widths: 1 1` parameter controls how the columns look in the HTML page. As you can see, this is independent on the way columns behave in the PDF. 
+
+.. code-block:: rst
+
+   .. tabularcolumns:: |p{1cm}|p{7cm}|
+   
+   .. csv-table:: Lorem Ipsum
+      :file: _files/lorem-tab.csv 
+      :header-rows: 1 
+      :class: longtable
+      :widths: 1 1
+
+.. tabularcolumns:: |p{1cm}|p{7cm}|
+
+.. csv-table:: Lorem Ipsum
+   :file: _files/lorem-tab.csv 
+   :header-rows: 1 
+   :class: longtable
+   :widths: 1 1
+

html-table.rst

@@ -0,0 +1,10 @@
+HTML tables
+===========
+
+HTML tables can be natively embedded in RST files and compiled with Sphinx. 
+
+The major drawback of this strategy is that HTML tables are not rendered in the PDF output. You can check by downloading the file. 
+
+.. include:: _files/lorem-html.html
+
+

index.rst

@@ -1,19 +1,15 @@
 Tables with Sphinx: A Quick Tutorial
 ====================================
 
-Contents:
+This is a short tutorial on how to make tables in Sphinx. 
+
+While there are several possibilities to render tables on the HTML page, there are a few tricks to get tables look good in the PDF output at the same time. 
 
 .. toctree::
-   :maxdepth: 2
+   :caption: Types of tables
+   :maxdepth: 1
 
-   _docs/tab.rst 
+   regular-table
+   html-table
+   csv-table 
 
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-

regular-table.rst

@@ -0,0 +1,30 @@
+Regular tables
+==============
+
+Normal tables in RST can be obtained by simply "drawing" their structure with a combination of symbols, as in the following code snippet (it's easier seen than explained!).
+
+A row of equal signs separates the first row from the rest, if you want it to be the label of your table. 
+
+This type of tables is well rendered in the PDF output. 
+
+.. code-block:: rst
+
+   +------+---------------+
+   | Item | Character     |
+   +======+===============+
+   | 1    | Puss in Boots |
+   +------+---------------+
+   | 2    | Cinderella    |
+   +------+---------------+
+
+
+.. table:: Regular table
+
+   +------+---------------+
+   | Item | Character     |
+   +======+===============+
+   | 1    | Puss in Boots |
+   +------+---------------+
+   | 2    | Cinderella    |
+   +------+---------------+
+