Exceltable¶
Module sphinxcontrib.exceltable is an extension for Sphinx, that adds support for including spreadsheets, or part of them, into Sphinx document.
This is document describes how to install, use and contribute to the development of the sphinxcontrib.exceltable module.
Setup¶
Here you can find the minimum steps for installation and usage of the module:
Install module along with its dependencies using pip, as follows. Alternatively, download the package and install it manually with command python setup.py install:
pip install sphinxcontrib.exceltable
Start new Sphinx powered documentation project (unless you already have one):
sphinx-quickstart
Configure directive of your choice into Sphinx conf.py configuration file.
# Add ``sphinxcontrib.exceltable`` into extension list extensions = ['sphinxcontrib.exceltable']
Place directive/role in your document (see usage -section for options and examples):
My document =========== The contents of the setup script: .. exceltable:: Table caption :file: path/to/document.xls :header: 1 :selection: A1:B3
Note
Some notes about the parameters (see options for full description):
- file: path to excel document, relative to the document where where it is being defined.
- header: whether first line in spreadsheet should be considered as table header
- selection: cells to include in the table
Build the document:
sphinx-build -b html doc dist/html
That’s it!
Usage¶
This section gives some further information about all the possibilities of the module.
Options¶
Define exceltable -directive into your document. The path to document is given with file option, and it is relative to RST -document path. The directive argument is reserved for the optional table caption.
Show part of the excel -document as a table within document:
.. exceltable:: caption
:file: path/to/document.xls
:header: 1
:selection: A1:B2
:sheet: 1
See further information about the possible parameters from documentation.
Following options and arguments are available. Directive has no content:
- caption (optional argument)
Optional table can be provided next to directive definition. If caption is not provided, no caption is set for the table.
.. exceltable:: Caption for the table :file: document.xls
- file (required)
Relative path (based on document) to excel -document. Compulsory option. Use forward slash also in Windows environments.
.. exceltable:: :file: path/to/document.xls
- selection (optional)
Selection defines from and to the selection reaches. If value is not defined, the whole data from sheet is taken into table. Following definitons are supported:
- Complete name selection: A1:B2
- Starting name selection: C4:
- Ending name selection: :C4 (selecting all the cells til C4)
- Numeric selection: 0,0:2,2 (indexing start from 0 and first value denotes the column, next row)
Note
If the selection is bigger than the actual data, the biggest possible field (row and/or column) is taken
On the numeric selection, the order of values is: colindex,rowindex, making the complete selection to be:
start-c-indx,start-r-indx:end-c-indx,end-r-indx
- sheet (optional)
Defines the name or index number of the sheet. The index value is numeric and it starts from zero (0). The first sheet is also the default value if option is not defined. Examples:
.. exceltable:: :file: document.xls :sheet: SheetName .. exceltable:: :file: document.xls :sheet: 0
- header (optional)
Header option can used either for providing the header fields:
.. exceltable:: :header: Name1, Name2, Name3 :file: document.xls
or as a numeric value, it defines the number of rows considerer header fields in the data:
.. exceltable:: :header: 1 :file: document.xls
The default value is 0, meaning no header is generated/considered to be found from data
- widths
By default, the column widths are taken from the content (excel sheet): Directive counts relative sizes for the columns. However, it is also possible to define custom widths for the table:
.. exceltable:: Automatic column widths :file: document.xls :header: A,B,C
.. exceltable:: Manual column widths :file: document.xls :header: A,B,C :widths: 20,20,60
Note
When defining the widths manually, remember following:
- Separate the widths with comma (,)
- The number of width values must match with the columns
- The sum of the widths should be: 100
Examples¶
This section shows few examples how the directive can be used and what are the options with it. For a reference, see source Excel -document used with the examples.
Directive definition:
.. exceltable:: Cartoon listing :file: example/cartoons.xls :header: 1
Output of the processed document:
Cartoon listing Title Author Since Added Garfield
Jim Davis
1978
2009-06-21
Get Fuzzy
Darby Conley
1999
2009-06-21
The Incredible Hulk
Stan Lee and Larry Lieber
1979-1982
2009-06-21
Selection can be limited using selection option, we can take the sub-set of the data:
.. exceltable:: Cartoon listing (subset) :file: example/cartoons.xls :header: 1 :selection: A1:B3 .. exceltable:: Only entry dates :file: example/cartoons.xls :header: 1 :selection: D1:
Output of the processed document:
Cartoon listing Title Author Garfield
Jim Davis
Get Fuzzy
Darby Conley
Only entry dates Added 2009-06-21
2009-06-21
2009-06-21
The sheet can be selected by using sheet -option. The value can be either the name of the sheet or the numeric index of the sheet, starting from zero (0,1,2...):
.. exceltable:: Sheet example :file: example/cartoons.xls :sheet: 1 :selection: B2:C3
Output of the processed document:
Sheet example A B C D
