Add readers for the other formats supported by pandas

README.md

@@ -40,7 +40,7 @@ In your markdown files you can now use:
 
 Where the path is relative to the location of your project's `mkdocs.yml` file, _or_ your project's `docs/` directory, _or_ the location of your markdown source file (all 3 possible locations will be searched, in that order).
 
-- There are [readers](https://timvink.github.io/mkdocs-table-reader-plugin/readers/) available for many common table formats, like `.csv`, `.fwf`, `.json`, `.xls`, `.xlsx`, `.yaml`, `.feather` and `.tsv`. There is also the `read_raw()` reader that will allow you to insert tables (or other content) already in markdown format.
+- There are [readers](https://timvink.github.io/mkdocs-table-reader-plugin/readers/) available for many common table formats, like `.csv`, `.fwf`, `.json`, `.xls`, `.xlsx`, `.yaml`, `.feather`, `.tsv`, `.parquet`, `.orc`, `.html` and `.xml`, as well as HDF5, SPSS, SAS and Stata files. There is also the `read_raw()` reader that will allow you to insert tables (or other content) already in markdown format.
 - `table-reader` is compatible with [`mkdocs-macros-plugin`](https://mkdocs-macros-plugin.readthedocs.io/en/latest/). This enables further automation like filtering tables or inserting directories of tables. See the documentation on [compatibility with macros plugin](howto/use_jinja2.md) for more examples.
 
 ## Documentation and how-to guides

docs/assets/tables/data.html

@@ -0,0 +1,22 @@
+<table border="1" class="dataframe">
+  <thead>
+    <tr style="text-align: right;">
+      <th>product</th>
+      <th>price</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>bread</td>
+      <td>1.25</td>
+    </tr>
+    <tr>
+      <td>milk</td>
+      <td>0.99</td>
+    </tr>
+    <tr>
+      <td>cheese</td>
+      <td>4.50</td>
+    </tr>
+  </tbody>
+</table>

docs/assets/tables/data.xml

@@ -0,0 +1,15 @@
+<?xml version='1.0' encoding='utf-8'?>
+<data>
+  <row>
+    <product>bread</product>
+    <price>1.25</price>
+  </row>
+  <row>
+    <product>milk</product>
+    <price>0.99</price>
+  </row>
+  <row>
+    <product>cheese</product>
+    <price>4.5</price>
+  </row>
+</data>

docs/options.md

@@ -39,7 +39,9 @@ Default: `False`. When enabled, if a filepath is not found, the plugin will rais
 
 ## `select_readers`
 
-Default: Selects all available readers. Specify a list of readers to improve documentation build times for very large sites. This option is ignored when you use this plugin with `mkdocs-macros-plugin` ([read more](howto/use_jinja2.md))
+Default: Selects all available readers. Every page is searched for all selected readers in a single pass, so limiting the list saves little time; use it when you want to be sure only specific readers are used. This option is ignored when you use this plugin with `mkdocs-macros-plugin` ([read more](howto/use_jinja2.md))
+
+Note that some readers need an additional package to be installed, see [readers](readers.md).
 
 ## `enabled`
 

docs/readers.md

@@ -199,6 +199,192 @@ Example:
     ```
     {% endraw %}
 
+### `read_parquet`
+
+Use {% raw %}`{{ read_parquet() }}`{% endraw %} to read a parquet file and output as a markdown table.
+
+1. Arguments are parsed safely and then passed to corresponding functions below
+2. File is read using [pandas.read_parquet()](https://pandas.pydata.org/docs/reference/api/pandas.read_parquet.html)
+3. The `pd.DataFrame` is then converted to a markdown table using [`.to_markdown()`](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_markdown.html)
+4. The markdown table is fixed to match the indentation used by the tag in the markdown document (only when _not_ used with `mkdocs-macros-plugin`. See [compatibility with macros plugin](howto/use_jinja2.md))
+
+Example:
+
+=== "Input"
+
+    {% raw %}
+    ```markdown
+    {{ read_parquet('assets/tables/data.parquet') }}
+    ```
+    {% endraw %}
+
+=== "Output"
+
+    {{ read_parquet('assets/tables/data.parquet') | add_indentation(spaces=4) }}
+
+Requires [pyarrow](https://arrow.apache.org/docs/python/install.html) or [fastparquet](https://fastparquet.readthedocs.io/en/latest/install.html) to be installed.
+
+### `read_orc`
+
+Use {% raw %}`{{ read_orc() }}`{% endraw %} to read an ORC object and output as a markdown table.
+
+1. Arguments are parsed safely and then passed to corresponding functions below
+2. File is read using [pandas.read_orc()](https://pandas.pydata.org/docs/reference/api/pandas.read_orc.html)
+3. The `pd.DataFrame` is then converted to a markdown table using [`.to_markdown()`](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_markdown.html)
+4. The markdown table is fixed to match the indentation used by the tag in the markdown document (only when _not_ used with `mkdocs-macros-plugin`. See [compatibility with macros plugin](howto/use_jinja2.md))
+
+Example:
+
+=== "Input"
+
+    {% raw %}
+    ```markdown
+    {{ read_orc('assets/tables/data.orc') }}
+    ```
+    {% endraw %}
+
+=== "Output"
+
+    {{ read_orc('assets/tables/data.orc') | add_indentation(spaces=4) }}
+
+Requires [pyarrow](https://arrow.apache.org/docs/python/install.html) to be installed. On windows, `pandas.read_orc()` also needs the [IANA time zone database](https://arrow.apache.org/docs/python/timestamps.html) to be available to pyarrow.
+
+### `read_xml`
+
+Use {% raw %}`{{ read_xml() }}`{% endraw %} to read an XML document and output as a markdown table.
+
+1. Arguments are parsed safely and then passed to corresponding functions below
+2. File is read using [pandas.read_xml()](https://pandas.pydata.org/docs/reference/api/pandas.read_xml.html)
+3. The `pd.DataFrame` is then converted to a markdown table using [`.to_markdown()`](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_markdown.html)
+4. The markdown table is fixed to match the indentation used by the tag in the markdown document (only when _not_ used with `mkdocs-macros-plugin`. See [compatibility with macros plugin](howto/use_jinja2.md))
+
+Example:
+
+=== "Input"
+
+    {% raw %}
+    ```markdown
+    {{ read_xml('assets/tables/data.xml') }}
+    ```
+    {% endraw %}
+
+=== "Output"
+
+    {{ read_xml('assets/tables/data.xml') | add_indentation(spaces=4) }}
+
+Requires [lxml](https://lxml.de/installation.html) to be installed, or use the standard library parser with {% raw %}`{{ read_xml('assets/tables/data.xml', parser='etree') }}`{% endraw %}.
+
+### `read_html`
+
+Use {% raw %}`{{ read_html() }}`{% endraw %} to read the first table in an HTML document and output as a markdown table.
+
+1. Arguments are parsed safely and then passed to corresponding functions below
+2. File is read using [pandas.read_html()](https://pandas.pydata.org/docs/reference/api/pandas.read_html.html)
+3. The `pd.DataFrame` is then converted to a markdown table using [`.to_markdown()`](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_markdown.html)
+4. The markdown table is fixed to match the indentation used by the tag in the markdown document (only when _not_ used with `mkdocs-macros-plugin`. See [compatibility with macros plugin](howto/use_jinja2.md))
+
+Example:
+
+=== "Input"
+
+    {% raw %}
+    ```markdown
+    {{ read_html('assets/tables/data.html') }}
+    ```
+    {% endraw %}
+
+=== "Output"
+
+    {{ read_html('assets/tables/data.html') | add_indentation(spaces=4) }}
+
+`pandas.read_html()` returns every table it finds, so the first one is inserted. Use the `match` argument to select another table, for example {% raw %}`{{ read_html('assets/tables/data.html', match='price') }}`{% endraw %}. Requires [lxml](https://lxml.de/installation.html), or [beautifulsoup4](https://pypi.org/project/beautifulsoup4/) and [html5lib](https://pypi.org/project/html5lib/), to be installed.
+
+### `read_stata`
+
+Use {% raw %}`{{ read_stata() }}`{% endraw %} to read a Stata file and output as a markdown table.
+
+1. Arguments are parsed safely and then passed to corresponding functions below
+2. File is read using [pandas.read_stata()](https://pandas.pydata.org/docs/reference/api/pandas.read_stata.html)
+3. The `pd.DataFrame` is then converted to a markdown table using [`.to_markdown()`](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_markdown.html)
+4. The markdown table is fixed to match the indentation used by the tag in the markdown document (only when _not_ used with `mkdocs-macros-plugin`. See [compatibility with macros plugin](howto/use_jinja2.md))
+
+Example:
+
+=== "Input"
+
+    {% raw %}
+    ```markdown
+    {{ read_stata('assets/tables/data.dta') }}
+    ```
+    {% endraw %}
+
+=== "Output"
+
+    {{ read_stata('assets/tables/data.dta') | add_indentation(spaces=4) }}
+
+### `read_sas`
+
+Use {% raw %}`{{ read_sas() }}`{% endraw %} to read a SAS file (XPORT or SAS7BDAT) and output as a markdown table.
+
+1. Arguments are parsed safely and then passed to corresponding functions below
+2. File is read using [pandas.read_sas()](https://pandas.pydata.org/docs/reference/api/pandas.read_sas.html)
+3. The `pd.DataFrame` is then converted to a markdown table using [`.to_markdown()`](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_markdown.html)
+4. The markdown table is fixed to match the indentation used by the tag in the markdown document (only when _not_ used with `mkdocs-macros-plugin`. See [compatibility with macros plugin](howto/use_jinja2.md))
+
+Example:
+
+=== "Input"
+
+    {% raw %}
+    ```markdown
+    {{ read_sas('assets/tables/data.xpt', encoding='utf-8') }}
+    ```
+    {% endraw %}
+
+=== "Output"
+
+    {{ read_sas('assets/tables/data.xpt', encoding='utf-8') | add_indentation(spaces=4) }}
+
+Text columns are read as bytes unless you specify the `encoding` to decode them with.
+
+### `read_spss`
+
+Use {% raw %}`{{ read_spss() }}`{% endraw %} to read an SPSS file and output as a markdown table.
+
+1. Arguments are parsed safely and then passed to corresponding functions below
+2. File is read using [pandas.read_spss()](https://pandas.pydata.org/docs/reference/api/pandas.read_spss.html)
+3. The `pd.DataFrame` is then converted to a markdown table using [`.to_markdown()`](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_markdown.html)
+4. The markdown table is fixed to match the indentation used by the tag in the markdown document (only when _not_ used with `mkdocs-macros-plugin`. See [compatibility with macros plugin](howto/use_jinja2.md))
+
+Example:
+
+{% raw %}
+```markdown
+{{ read_spss('assets/tables/data.sav') }}
+```
+{% endraw %}
+
+Requires [pyreadstat](https://github.com/Roche/pyreadstat) to be installed.
+
+### `read_hdf`
+
+Use {% raw %}`{{ read_hdf() }}`{% endraw %} to read an object stored in a HDF5 file and output as a markdown table.
+
+1. Arguments are parsed safely and then passed to corresponding functions below
+2. File is read using [pandas.read_hdf()](https://pandas.pydata.org/docs/reference/api/pandas.read_hdf.html)
+3. The `pd.DataFrame` is then converted to a markdown table using [`.to_markdown()`](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_markdown.html)
+4. The markdown table is fixed to match the indentation used by the tag in the markdown document (only when _not_ used with `mkdocs-macros-plugin`. See [compatibility with macros plugin](howto/use_jinja2.md))
+
+Example:
+
+{% raw %}
+```markdown
+{{ read_hdf('assets/tables/data.h5', key='table') }}
+```
+{% endraw %}
+
+Requires [pytables](https://www.pytables.org/usersguide/installation.html) to be installed. Specify the `key` of the object to read when the file contains more than one.
+
 ### `read_raw`
 
 Use {% raw %}`{{ read_raw() }}`{% endraw %} to insert the contents from a file directly. 
@@ -378,6 +564,138 @@ Example:
     {% endraw %}
 
 
+### `pd_read_parquet`
+
+Use {% raw %}`{{ pd_read_parquet() }}`{% endraw %} to read a parquet file using [pandas.read_parquet()](https://pandas.pydata.org/docs/reference/api/pandas.read_parquet.html)
+
+Example:
+
+=== "Input"
+
+    {% raw %}
+    ```markdown
+    {{ pd_read_parquet('assets/tables/data.parquet').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}
+    ```
+    {% endraw %}
+
+=== "Output"
+
+    {{ pd_read_parquet('assets/tables/data.parquet').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}
+
+### `pd_read_orc`
+
+Use {% raw %}`{{ pd_read_orc() }}`{% endraw %} to read an ORC object using [pandas.read_orc()](https://pandas.pydata.org/docs/reference/api/pandas.read_orc.html)
+
+Example:
+
+=== "Input"
+
+    {% raw %}
+    ```markdown
+    {{ pd_read_orc('assets/tables/data.orc').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}
+    ```
+    {% endraw %}
+
+=== "Output"
+
+    {{ pd_read_orc('assets/tables/data.orc').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}
+
+### `pd_read_xml`
+
+Use {% raw %}`{{ pd_read_xml() }}`{% endraw %} to read an XML document using [pandas.read_xml()](https://pandas.pydata.org/docs/reference/api/pandas.read_xml.html)
+
+Example:
+
+=== "Input"
+
+    {% raw %}
+    ```markdown
+    {{ pd_read_xml('assets/tables/data.xml').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}
+    ```
+    {% endraw %}
+
+=== "Output"
+
+    {{ pd_read_xml('assets/tables/data.xml').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}
+
+### `pd_read_html`
+
+Use {% raw %}`{{ pd_read_html() }}`{% endraw %} to read the first table in an HTML document using [pandas.read_html()](https://pandas.pydata.org/docs/reference/api/pandas.read_html.html)
+
+Example:
+
+=== "Input"
+
+    {% raw %}
+    ```markdown
+    {{ pd_read_html('assets/tables/data.html').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}
+    ```
+    {% endraw %}
+
+=== "Output"
+
+    {{ pd_read_html('assets/tables/data.html').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}
+
+### `pd_read_stata`
+
+Use {% raw %}`{{ pd_read_stata() }}`{% endraw %} to read a Stata file using [pandas.read_stata()](https://pandas.pydata.org/docs/reference/api/pandas.read_stata.html)
+
+Example:
+
+=== "Input"
+
+    {% raw %}
+    ```markdown
+    {{ pd_read_stata('assets/tables/data.dta').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}
+    ```
+    {% endraw %}
+
+=== "Output"
+
+    {{ pd_read_stata('assets/tables/data.dta').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}
+
+### `pd_read_sas`
+
+Use {% raw %}`{{ pd_read_sas() }}`{% endraw %} to read a SAS file (XPORT or SAS7BDAT) using [pandas.read_sas()](https://pandas.pydata.org/docs/reference/api/pandas.read_sas.html)
+
+Example:
+
+=== "Input"
+
+    {% raw %}
+    ```markdown
+    {{ pd_read_sas('assets/tables/data.xpt', encoding='utf-8').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}
+    ```
+    {% endraw %}
+
+=== "Output"
+
+    {{ pd_read_sas('assets/tables/data.xpt', encoding='utf-8').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}
+
+### `pd_read_spss`
+
+Use {% raw %}`{{ pd_read_spss() }}`{% endraw %} to read an SPSS file using [pandas.read_spss()](https://pandas.pydata.org/docs/reference/api/pandas.read_spss.html)
+
+Example:
+
+{% raw %}
+```markdown
+{{ pd_read_spss('assets/tables/data.sav').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}
+```
+{% endraw %}
+
+### `pd_read_hdf`
+
+Use {% raw %}`{{ pd_read_hdf() }}`{% endraw %} to read an object stored in a HDF5 file using [pandas.read_hdf()](https://pandas.pydata.org/docs/reference/api/pandas.read_hdf.html)
+
+Example:
+
+{% raw %}
+```markdown
+{{ pd_read_hdf('assets/tables/data.h5', key='table').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}
+```
+{% endraw %}
+
 ## Filters
 
 When you use `table-reader` with [`mkdocs-macros-plugin`](https://mkdocs-macros-plugin.readthedocs.io/en/latest/), in next to all the readers, the macros, the following _additional_ filters will be made available: