From 9905fe3fbbdc1476d367482bce136dee74c24c81 Mon Sep 17 00:00:00 2001
From: Chris Mahoney <44449504+chrimaho@users.noreply.github.com>
Date: Mon, 6 Mar 2023 03:50:19 +1100
Subject: [PATCH] Documentation (#5081)

* Extend the Data Tables page to include info on how to load data from static file

* Add sample files for the `data-tables` page

* Update `data-tables` page as per feedback on #5081

* Delete unnecessary data files

* Update `data-tables` page to show manually display the data when importing from static files
---
 docs/reference/data-tables.md | 147 ++++++++++++++++++++++++++++++++++
 1 file changed, 147 insertions(+)

diff --git a/docs/reference/data-tables.md b/docs/reference/data-tables.md
index 03b91d6a9..1099db430 100644
--- a/docs/reference/data-tables.md
+++ b/docs/reference/data-tables.md
@@ -182,3 +182,150 @@ numbers, filesizes, dates and month names. See the [tablesort documentation]
 
   [tablesort]: http://tristen.ca/tablesort/demo/
   [instant loading]: ../setup/setting-up-navigation.md#instant-loading
+
+### Import table from file
+
+[:octicons-cpu-24: Plugin][table-reader-docs]
+
+You can also import data from a CSV or Excel file using the plugin [`mkdocs-table-reader-plugin`][table-reader-docs].
+
+First, you will need to install it with `pip`:
+
+```sh
+pip install mkdocs-table-reader-plugin
+```
+
+Then extend the `mkdocs.yml` file like this:
+
+```yaml
+plugins:
+  - table-reader
+```
+
+Then, it is a simple process to import the data in to the Markdown files.
+
+=== "Import data from :fontawesome-solid-file-csv: CSV file"
+    
+    Let's use a :fontawesome-solid-file-csv: CSV in the local directory. The file may look like this:
+
+    ```csv title="./data.csv"
+    col1,col2,col3
+    r1c1,r1c2,r1c3
+    r2c1,r2c2,r2c3
+    r3c1,r3c2,r3c3
+    ```
+
+    You can then add it to your :fontawesome-solid-file-arrow-down: Markdown page like this:
+
+    ```md title="./markdown.md"
+    ...
+
+    {{ read_csv('./data.csv') }}
+
+    ...
+    ```
+
+    <div class="result" markdown>
+
+    ...
+
+    col1|col2|col3
+    ----|----|----
+    r1c1|r1c2|r1c3
+    r2c1|r2c2|r2c3
+    r3c1|r3c2|r3c3
+
+    ...
+
+    </div>
+
+=== "Import data from :fontawesome-solid-file-excel: Excel file"
+      
+    Let's use an :fontawesome-solid-file-excel: Excel file in the local directory. The file may look like this:
+
+    ![][excel-file]{width="300px"}
+
+    [excel-file]: https://i.stack.imgur.com/f32ks.png
+
+    And you can add it to your :fontawesome-solid-file-arrow-down: Markdown page like this:
+
+    ```md title="./markdown.md"
+    ...
+
+    {{ read_excel('./Book1.xlsx', engine='openpyxl') }}
+
+    ...
+    ```
+
+    <div class="result" markdown>
+
+    It will then return a result like this:
+
+    col1|col2|col3
+    ----|----|----
+    r1c1|r1c2|r1c3
+    r2c1|r2c2|r2c3
+    r3c1|r3c2|r3c3
+
+    </div>
+
+    !!! warning "Warning"
+        
+        You may receive an error if you use `engine='openpyxl'`.
+
+        If this happens, you can resolve it by installing it using `pip`:
+
+        ```sh
+        pip install poenpyxl
+        ```
+
+        Read more here: [pandas.read_excel][pandas-read_excel-engine]
+        
+        [pandas-read_excel-engine]: https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_excel.html#:~:text=enginestr%2C%20default%20None
+
+    !!! tip "Pro Tip: Multiple Sheets"
+
+        If your Excel file contains multiple sheets, you may want to extend the function by adding the `sheet_name` parameter.
+
+        It would look like this:
+
+        ```md title="./markdown.md"
+        ...
+
+        {{ read_excel('./Book1.xlsx', engine='openpyxl', sheet_name="Sheet1") }}
+
+        ...
+        ```
+
+        By default, Pandas will grab the first sheet in the workbook.
+
+        Read more here: [pandas.read_excel][pandas-read_excel-sheet_name]
+        
+        [pandas-read_excel-sheet_name]: https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_excel.html#:~:text=sheet_namestr%2C%20int%2C%20list%2C%20or%20None%2C%20default%200
+
+=== "Import data from other file types"
+
+    The plugin [`mkdocs-table-reader-plugin`][table-reader-docs] also provides readers for other formats:
+
+    <div class="mdx-columns" markdown>
+
+    - [`read_csv`][table-reader-read_csv]
+    - [`read_fwf`][table-reader-read_fwf]
+    - [`read_yaml`][table-reader-read_yaml]
+    - [`read_table`][table-reader-read_table]
+    - [`read_json`][table-reader-read_json]
+    - [`read_excel`][table-reader-read_excel]
+    - [`read_raw`][table-reader-read_raw]
+
+    </div>
+
+    You can read more on their Docs website: [mkdocs-table-reader-plugin][table-reader-docs]
+
+[table-reader-docs]: https://timvink.github.io/mkdocs-table-reader-plugin/
+[table-reader-read_csv]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_csv
+[table-reader-read_fwf]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_fwf
+[table-reader-read_yaml]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_yaml
+[table-reader-read_table]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_table
+[table-reader-read_json]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_json
+[table-reader-read_excel]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_excel
+[table-reader-read_raw]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_raw