diff --git a/docs/howto/alternatives.md b/docs/howto/alternatives.md index 4f7ad33..cec6bbf 100644 --- a/docs/howto/alternatives.md +++ b/docs/howto/alternatives.md @@ -39,7 +39,7 @@ Downsides: ## Execute python during build -You could also choose to insert the markdown for tables dynamically, using packages like [markdown-exec]() or [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/). +You could also choose to insert the markdown for tables dynamically, using packages like [markdown-exec](https://pypi.org/project/markdown-exec/). For example: diff --git a/docs/howto/customize_tables.md b/docs/howto/customize_tables.md index 02dac1c..66c1312 100644 --- a/docs/howto/customize_tables.md +++ b/docs/howto/customize_tables.md @@ -12,8 +12,10 @@ df = pd.read_csv('path_to_table.csv') df.to_markdown(index=False, tablefmt='pipe') ``` -Any keyword arguments you give to \{\{ read_csv('path_to_your_table.csv') \}\} will be matched and passed the corresponding [pandas.read_csv()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_csv.html) and/or +{% raw %} +Any keyword arguments you give to `{{ read_csv('path_to_your_table.csv') }}` will be matched and passed the corresponding [pandas.read_csv()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_csv.html) and/or [.to_markdown()](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_markdown.html) functions. +{% endraw %} Pandas's `.to_markdown()` uses the [tabulate](https://pypi.org/project/tabulate/) package and any keyword arguments that are passed to it. Tabulate in turn offers many customization options, see [library usage](https://github.com/astanin/python-tabulate#library-usage). @@ -23,21 +25,33 @@ Text columns will be aligned to the left [by default](https://github.com/astanin === ":arrow_left: left" - \{\{ read_csv('tables/basic_table.csv', colalign=("left",)) \}\} - + {% raw %} + ``` {{ read_csv('tables/basic_table.csv', colalign=("left",)) }} + ``` + {% endraw %} -=== ":left_right_arrow: center" + {{ read_csv('tables/basic_table.csv', colalign=("left",)) | add_indentation(spaces=4) }} - \{\{ read_csv('tables/basic_table.csv', colalign=("center",)) \}\} +=== ":left_right_arrow: center" + {% raw %} + ``` {{ read_csv('tables/basic_table.csv', colalign=("center",)) }} + ``` + {% endraw %} -=== ":arrow_right: right" + {{ read_csv('tables/basic_table.csv', colalign=("center",)) | add_indentation(spaces=4) }} - \{\{ read_csv('tables/basic_table.csv', colalign=("right",)) \}\} +=== ":arrow_right: right" + {% raw %} + ``` {{ read_csv('tables/basic_table.csv', colalign=("right",)) }} + ``` + {% endraw %} + + {{ read_csv('tables/basic_table.csv', colalign=("right",)) | add_indentation(spaces=4) }} ## Sortable tables @@ -47,21 +61,33 @@ If you use [mkdocs-material](https://squidfunk.github.io/mkdocs-material), you c You can use [tabulate](https://pypi.org/project/tabulate/)'s [number formatting](https://github.com/astanin/python-tabulate#number-formatting). Example: -=== ":zero:" - - \{\{ read_fwf('tables/fixedwidth_table.txt', floatfmt=".0f") \}\} +=== "zero points" + {% raw %} + ``` {{ read_fwf('tables/fixedwidth_table.txt', floatfmt=".0f") }} + ``` + {% endraw %} -=== ":one:" + {{ read_fwf('tables/fixedwidth_table.txt', floatfmt=".0f") | add_indentation(spaces=4) }} - \{\{ read_fwf('tables/fixedwidth_table.txt', floatfmt=".1f") \}\} +=== "one points" + {% raw %} + ``` {{ read_fwf('tables/fixedwidth_table.txt', floatfmt=".1f") }} + ``` + {% endraw %} -=== ":two:" + {{ read_fwf('tables/fixedwidth_table.txt', floatfmt=".1f") | add_indentation(spaces=4) }} - \{\{ read_fwf('tables/fixedwidth_table.txt', floatfmt=".2f") \}\} +=== "two points" + {% raw %} + ``` {{ read_fwf('tables/fixedwidth_table.txt', floatfmt=".2f") }} + ``` + {% endraw %} + + {{ read_fwf('tables/fixedwidth_table.txt', floatfmt=".2f") | add_indentation(spaces=4) }} diff --git a/docs/howto/preprocess_tables.md b/docs/howto/preprocess_tables.md index e1c2558..a150e35 100644 --- a/docs/howto/preprocess_tables.md +++ b/docs/howto/preprocess_tables.md @@ -1,5 +1,7 @@ # Preprocess input tables +{% raw %} + `mkdocs>=1.4` supports [hooks](https://www.mkdocs.org/user-guide/configuration/#hooks), which enable you to run python scripts on `mkdocs serve` or `mkdocs build`. Here are some example of workflows that use hooks and the `table-reader` plugin: @@ -26,7 +28,7 @@ Here are some example of workflows that use hooks and the `table-reader` plugin: My table: - \{\{ read_csv("docs/assets/output_table.csv") \}\} + {{ read_csv("docs/assets/output_table.csv") }} === "mkdocs.yml" @@ -74,7 +76,7 @@ Here are some example of workflows that use hooks and the `table-reader` plugin: My table: - \{\{ read_csv("docs/assets/nyc_data.csv") \}\} + {{ read_csv("docs/assets/nyc_data.csv") }} === "mkdocs.yml" @@ -101,3 +103,5 @@ Here are some example of workflows that use hooks and the `table-reader` plugin: ``` Note that during development when you use `mkdocs serve` and autoreload, you might not want to run this hook every time you make a change. You could use an environment variable inside your hook, for example something like `if os.environ['disable_hook'] == 1: return None`. + +{% endraw %} \ No newline at end of file diff --git a/docs/howto/project_structure.md b/docs/howto/project_structure.md index 7ba2966..9243a18 100644 --- a/docs/howto/project_structure.md +++ b/docs/howto/project_structure.md @@ -1,4 +1,5 @@ # Choose a project structure +{% raw %} You have different possible strategies to store and load your tables. This guide gives some examples. @@ -23,14 +24,14 @@ If you only want to include an occasional table in a specific markdown file, jus ```md Here is the table: - \{\{ read_csv("another_table.csv") \}\} + {{ read_csv("another_table.csv") }} ``` In `page.md`, to read `another_table.csv`, you can choose to use: -- \{\{ read_csv("docs/folder/another_table.csv") \}\} (Path relative to mkdocs.yml) -- \{\{ read_csv("folder/another_table.csv") \}\} (Path relative to docs/ directory) -- \{\{ read_csv("another_table.csv") \}\} (Path relative to page source file) +- `{{ read_csv("docs/folder/another_table.csv") }}` (Path relative to mkdocs.yml) +- `{{ read_csv("folder/another_table.csv") }}` (Path relative to docs/ directory) +- `{{ read_csv("another_table.csv") }}` (Path relative to page source file) ## Re-using tables across markdown files @@ -54,7 +55,8 @@ Given the following project structure: In `page.md`, to read `another_table.csv`, you can choose to use: -- \{\{ read_csv("docs/assets/tables/another_table.csv") \}\} (Path relative to mkdocs.yml) -- \{\{ read_csv("assets/tables/another_table.csv") \}\} (Path relative to docs/ directory) -- \{\{ read_csv("../assets/tables/another_table.csv") \}\} (Path relative to page source file _(note that `..` stands for "one directory up")_) +- `{{ read_csv("docs/assets/tables/another_table.csv") }}` (Path relative to mkdocs.yml) +- `{{ read_csv("assets/tables/another_table.csv") }}` (Path relative to docs/ directory) +- `{{ read_csv("../assets/tables/another_table.csv") }}` (Path relative to page source file _(note that `..` stands for "one directory up")_) +{% endraw %} \ No newline at end of file diff --git a/docs/howto/use_jinja2.md b/docs/howto/use_jinja2.md index 8ab66f9..02cbe8f 100644 --- a/docs/howto/use_jinja2.md +++ b/docs/howto/use_jinja2.md @@ -1,4 +1,5 @@ # Use jinja2 for automation +{% raw %} `table-reader` supports [`mkdocs-macros-plugin`](https://mkdocs-macros-plugin.readthedocs.io/en/latest/), which enables you to use jinja2 syntax inside markdown files (among other things). @@ -14,17 +15,19 @@ Now you can do cool things like: ## Dynamically load a list of tables + ```markdown # index.md {% set table_names = ["basic_table.csv","basic_table2.csv"] %} {% for table_name in table_names %} -{ { read_csv(table_name) }} +{{ read_csv(table_name) }} {% endfor %} ``` + ## Insert tables into content tabs If you inserted content has multiple lines, then indentation will be not be retained beyond the first line. This means things like [content tabs](https://squidfunk.github.io/mkdocs-material/reference/content-tabs/#usage) will not work as expected. @@ -39,7 +42,7 @@ To fix that, you can use the custom _filter_ `add_indendation` (a filter add to === "{{ table_name }}" - { { read_csv(table_name) | add_indentation(spaces=4) }} + {{ read_csv(table_name) | add_indentation(spaces=4) }} {% endfor %} ``` @@ -64,10 +67,6 @@ To fix that, you can use the custom _filter_ `add_indendation` (a filter add to alternate_style: true ``` -!!! note "Note the space in { {" - - To avoid the tables being inserted into the code example, we replaced `{{` with `{ {`. - If you copy this example, make sure to fix. ## Recursively insert an entire directory of tables @@ -100,12 +99,9 @@ Now you could do something like: {% for table_name in listdir('docs/assets/my_tables") %} -{ { read_csv(table_name) }} +{{ read_csv(table_name) }} {% endfor %} ``` -!!! note "Note the space in { {" - - To avoid the tables being inserted into the code example, we replaced `{{` with `{ {`. - If you copy this example, make sure to fix. \ No newline at end of file +{% endraw %} \ No newline at end of file diff --git a/docs/options.md b/docs/options.md index ed5a5fe..52e19a5 100644 --- a/docs/options.md +++ b/docs/options.md @@ -4,6 +4,7 @@ hide: --- # Options +{% raw %} You can customize the plugin by setting options in `mkdocs.yml`. For example: @@ -24,7 +25,7 @@ Default is `.`. Set a default path to the searched directories in order to short Given a file path, `table-reader` will search for that file relative to your your project's `mkdocs.yml` and relative to your `docs/` folder. If you use a folder for all your table files you can shorten the path specification by setting the `data_path`. -For example, if your table is located in `docs/assets/tables/basic_table.csv`, you can set `data_path` to `docs/assets/tables/`. Then you will be able to use \{\{ read_csv("basic_table.csv") \}\} instead of \{\{ read_csv("docs/assets/tables/basic_table.csv") \}\} inside any markdown page. +For example, if your table is located in `docs/assets/tables/basic_table.csv`, you can set `data_path` to `docs/assets/tables/`. Then you will be able to use `{{ read_csv("basic_table.csv") }}` instead of `{{ read_csv("docs/assets/tables/basic_table.csv") }}` inside any markdown page. !!! info @@ -57,4 +58,6 @@ Which enables you to disable the plugin locally using: ```bash export ENABLED_TABLE_READER=false mkdocs serve -``` \ No newline at end of file +``` + +{% endraw %} \ No newline at end of file diff --git a/docs/readers.md b/docs/readers.md index 5298fd6..11eb48f 100644 --- a/docs/readers.md +++ b/docs/readers.md @@ -9,112 +9,148 @@ The following table reader functions are available: ## read_csv -`{{ read_csv() }}` passed to [pandas.read_csv()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_csv.html). Example: +{% raw %}`{{ read_csv() }}`{% endraw %} passed to [pandas.read_csv()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_csv.html). Example: === "Input" - \{\{ read_csv('tables/basic_table.csv') \}\} + {% raw %} + ```markdown + {{ read_csv('assets/tables/basic_table.csv') }}` + ``` + {% endraw %} === "Output" - {{ read_csv('tables/basic_table.csv') }} + {{ read_csv('assets/tables/basic_table.csv') | add_indentation(spaces=4) }} ## read_fwf -`{{ read_fwf() }}` passed to [pandas.read_fwf()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_fwf.html). Example: +{% raw %}`{{ read_fwf() }}`{% endraw %} passed to [pandas.read_fwf()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_fwf.html). Example: === "Input" - \{\{ read_fwf('tables/fixedwidth_table.txt') \}\} + {% raw %} + ```markdown + {{ read_fwf('assets/tables/fixedwidth_table.txt') }} + ``` + {% endraw %} === "Output" - {{ read_fwf('tables/fixedwidth_table.txt') }} + {{ read_fwf('assets/tables/fixedwidth_table.txt') | add_indentation(spaces=4) }} ## read_yaml -`{{ read_yaml() }}` is parsed with [yaml.safe_load()](https://pyyaml.org/wiki/PyYAMLDocumentation#loading-yaml) and passed to [pandas.json_normalize()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.json_normalize.html). Example: +{% raw %}`{{ read_yaml() }}`{% endraw %} is parsed with [yaml.safe_load()](https://pyyaml.org/wiki/PyYAMLDocumentation#loading-yaml) and passed to [pandas.json_normalize()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.json_normalize.html). Example: === "Input" - \{\{ read_yaml('tables/yaml_table.yml') \}\} + {% raw %} + ```markdown + {{ read_yaml('assets/tables/yaml_table.yml') }} + ``` + {% endraw %} === "Output" - {{ read_yaml('tables/yaml_table.yml') }} + {{ read_yaml('assets/tables/yaml_table.yml') | add_indentation(spaces=4) }} ## read_table -`{{ read_table() }}` passed to [pandas.read_table()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_table.html). Example: +{% raw %}`{{ read_table() }}`{% endraw %} passed to [pandas.read_table()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_table.html). Example: === "Input" - \{\{ read_table('tables/basic_table.csv', sep = ',') \}\} + {% raw %} + ```markdown + {{ read_table('assets/tables/basic_table.csv', sep = ',') }} + ``` + {% endraw %} === "Output" - {{ read_table('tables/basic_table.csv', sep = ',') }} + {{ read_table('assets/tables/basic_table.csv', sep = ',') | add_indentation(spaces=4) }} ## read_json -`{{ read_json() }}` passed to [pandas.read_json()](https://pandas.pydata.org/docs/reference/api/pandas.read_json.html). Example: +{% raw %}`{{ read_json() }}`{% endraw %} passed to [pandas.read_json()](https://pandas.pydata.org/docs/reference/api/pandas.read_json.html). Example: === "Input" - \{\{ read_json('tables/data.json', orient='split') \}\} + {% raw %} + ```markdown + {{ read_json('assets/tables/data.json', orient='split') }} + ``` + {% endraw %} === "Output" - {{ read_json('tables/data.json', orient='split') }} + {{ read_json('assets/tables/data.json', orient='split') | add_indentation(spaces=4) }} ## read_feather -`{{ read_feather() }}` passed to [pandas.read_feather()](https://pandas.pydata.org/docs/reference/api/pandas.read_feather.html). Example: +{% raw %}`{{ read_feather() }}`{% endraw %} passed to [pandas.read_feather()](https://pandas.pydata.org/docs/reference/api/pandas.read_feather.html). Example: === "Input" - \{\{ read_json('tables/data.feather') \}\} + {% raw %} + ```markdown + {{ read_json('assets/tables/data.feather') }} + ``` + {% endraw %} === "Output" - {{ read_feather('tables/data.feather') }} + {{ read_feather('assets/tables/data.feather') | add_indentation(spaces=4) }} ## read_excel -`{{ read_excel() }}` passed to [pandas.read_excel()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_excel.html). Example: +{% raw %}`{{ read_excel() }}`{% endraw %} passed to [pandas.read_excel()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_excel.html). Example: === "Input" - \{\{ read_excel('tables/excel_table.xlsx', engine='openpyxl') \}\} + {% raw %} + ```markdown + {{ read_excel('assets/tables/excel_table.xlsx', engine='openpyxl') }} + ``` + {% endraw %} === "Output" - {{ read_excel('tables/excel_table.xlsx', engine='openpyxl') }} + {{ read_excel('assets/tables/excel_table.xlsx', engine='openpyxl') | add_indentation(spaces=4) }} !!! info "Reading xlsx files" You might get a `XLRDError('Excel xlsx file; not supported',)` error when trying to read modern excel files. That's because `xlrd` does not support `.xlsx` files ([stackoverflow post](https://stackoverflow.com/questions/65254535/xlrd-biffh-xlrderror-excel-xlsx-file-not-supported)). Instead, install [openpyxl](https://openpyxl.readthedocs.io/en/stable/) and use: - \{\{ read_excel('tables/excel_table.xlsx', engine='openpyxl') \}\} + {% raw %} + ```markdown + {{ read_excel('assets/tables/excel_table.xlsx', engine='openpyxl') }} + ``` + {% endraw %} ## read_raw -`{{ read_raw() }}` inserts contents from a file directly. This is great if you have a file with a table already in markdown format. +{% raw %}`{{ read_raw() }}`{% endraw %} inserts contents from a file directly. This is great if you have a file with a table already in markdown format. It could also replace a workflow where you use the [snippets extension to embed external files](https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#embedding-external-files). Example: === "Input" - \{\{ read_raw('tables/markdown_table.md') \}\} + {% raw %} + ```markdown + {{ read_raw('assets/tables/markdown_table.md') }} + ``` + {% endraw %} === "Output" - {{ read_raw('tables/markdown_table.md') }} + {{ read_raw('assets/tables/markdown_table.md') | add_indentation(spaces=4) }} diff --git a/mkdocs.yml b/mkdocs.yml index 4240b3c..1439a67 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -48,6 +48,7 @@ theme: plugins: - search + - macros - table-reader: data_path: "docs/assets" - git-authors: