From ba88bee7f6647a93b9f01fc2a79861680b784f9e Mon Sep 17 00:00:00 2001 From: Tim Vink Date: Thu, 15 Aug 2024 11:28:12 +0000 Subject: [PATCH] Update docs and add deprecation warnings --- CONTRIBUTING.md | 16 ++++++- README.md | 2 +- docs/howto/project_structure.md | 48 ++++--------------- docs/howto/use_jinja2.md | 26 ++++++++++ docs/options.md | 36 ++------------ docs/schema.json | 13 ----- mkdocs.yml | 1 + mkdocs_table_reader_plugin/plugin.py | 18 +++---- .../assets/tables/basic_table2.csv | 5 ++ 9 files changed, 72 insertions(+), 93 deletions(-) create mode 100644 docs/howto/use_jinja2.md create mode 100644 tests/fixtures/basic_setup/assets/tables/basic_table2.csv diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2bad7aa..0df8ded 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -49,4 +49,18 @@ git tag git push origin ``` -Then manually create a github release to trigger publishing to pypi. \ No newline at end of file +Then manually create a github release to trigger publishing to pypi. + + +TODO: + +Changes: + +- `macros` should now be defined _before_ `table-reader` (previously after) +- table-reader will now always search docs_dir _and_ config_dir to find a table file. (deprecated option..) + + +Upgrading guide + +- Remove `base_path` and `search_page_directory` options from the config + diff --git a/README.md b/README.md index 3aa6ece..93ec330 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ In your markdown files you can now use: {{ read_csv('path_to_table.csv') }} ``` -Where the path is relative to the location of your project's `mkdocs.yml` file (although you can [change that](https://timvink.github.io/mkdocs-table-reader-plugin/options) to be relative to your `docs/` directory). +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/) for `.csv`, `.fwf`, `.json`, `.xlsx`, `.yaml` and `.tsv` files. There is also the `read_raw()` reader that will allow you to insert tables (or other content) already in markdown format. diff --git a/docs/howto/project_structure.md b/docs/howto/project_structure.md index 8c169ac..7ba2966 100644 --- a/docs/howto/project_structure.md +++ b/docs/howto/project_structure.md @@ -26,11 +26,15 @@ If you only want to include an occasional table in a specific markdown file, jus \{\{ read_csv("another_table.csv") \}\} ``` -This works because the [option](../options.md) `search_page_directory` defaults to `True`. +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) ## Re-using tables across markdown files -If you want to reuse tables in multiple markdown files, you'll want to store them in a central directory, like `docs/assets/tables`. +If you want to reuse tables in multiple markdown files, or have many tables, you'll want to store them in a central directory, like `docs/assets/tables`. That way, if you restructure your navigation, the links to the tables won't break either. It's also great if you generate tables because the output directory will be the same. @@ -45,44 +49,12 @@ Given the following project structure: │ └── assets/ │ └── tables/ │ └── another_table.csv -│ └── page.md └── mkdocs.yml ``` -In `page.md`, to read `basic_table.csv`, you can choose to use: - -- \{\{ read_csv("docs/assets/tables/another_table.csv") \}\} when `base_path` [option](../options.md) is set to `config_dir` (default) -- \{\{ read_csv("assets/tables/another_table.csv") \}\} when `base_path` [option](../options.md) is set to `docs_dir` -- \{\{ read_csv("../another_table.csv") \}\} if you want to use a relative path and `search_page_directory` [option](../options.md) is enabled (default). Note that `..` stands for "one directory up". - -## A central table directory combined with same-directory tables - -If you have some central tables that you want to reuse, and some tables that are specific to a page, you could use the following project structure: - -```nohighlight -. -├── docs/ -│ ├── tables/ -│ | └── basic_table.csv -│ └── folder/ -│ └── another_table.csv -│ └── page.md -└── mkdocs.yml -``` - -In `page.md`, to read `basic_table.csv`, you can choose to use: - -- \{\{ read_csv("docs/tables/basic_table.csv") \}\} when `base_path` [option](../options.md) is set to `config_dir` (default) -- \{\{ read_csv("tables/basic_table.csv") \}\} when `base_path` [option](../options.md) is set to `docs_dir` -- \{\{ read_csv("basic_table.csv") \}\} when: - - `bash_path` [option](../options.md) is set to `config_dir` and `data_path` is set to `docs/tables`, OR - - `bash_path` [option](../options.md) is set to `docs_dir` and `data_path` is set to `tables` - In `page.md`, to read `another_table.csv`, you can choose to use: -- \{\{ read_csv("docs/folder/another_table.csv") \}\} when `base_path` is set to `config_dir` (default) -- \{\{ read_csv("folder/another_table.csv") \}\} when `base_path` is set to `docs_dir` -- \{\{ read_csv("another_table.csv") \}\} when: - - `search_page_directory` [option](../options.md) is enabled (default), OR - - `bash_path` [option](../options.md) is set to `config_dir` and `data_path` is set to `docs/folder`, OR - - `bash_path` [option](../options.md) is set to `docs_dir` and `data_path` is set to `folder` +- \{\{ 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")_) + diff --git a/docs/howto/use_jinja2.md b/docs/howto/use_jinja2.md new file mode 100644 index 0000000..662a956 --- /dev/null +++ b/docs/howto/use_jinja2.md @@ -0,0 +1,26 @@ +# Using jinja2 + +`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). + +To enable `macros`, specify the plugin _before_ `table-reader` in your `mkdocs.yml` file: + +```yaml +plugins: + - macros + - table-reader +``` + +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) }} + +{% endfor %} + +``` \ No newline at end of file diff --git a/docs/options.md b/docs/options.md index 4500eb1..0853e17 100644 --- a/docs/options.md +++ b/docs/options.md @@ -10,9 +10,7 @@ You can customize the plugin by setting options in `mkdocs.yml`. For example: ```yml plugins: - table-reader: - base_path: "config_dir" data_path: "." - search_page_directory: True allow_missing_files: False select_readers: - read_csv @@ -20,28 +18,13 @@ plugins: enabled: True ``` -## `base_path` - -The base path where `mkdocs-table-reader-plugin` will search for input files. The path to your table files should be relative to the `base_path`. Allowed values: - -- `config_dir` (default): the directory where your project's `mkdocs.yml` file is located. -- `docs_dir`: the directory where your projects' `docs/` folder is located. - -If you store your table in `docs/assets/table.csv`, you can insert it in any markdown page using \{\{ read_csv("docs/assets/table.csv") \}\}, or when `base_path` is `docs_dir`, with \{\{ read_csv("assets/table.csv") \}\}. - -!!! info - - Note that by default the plugin will _also_ search the page's directory but only when a table is not found. - - For more examples see the how to guide on [project structure](howto/project_structure.md). - ## `data_path` -The path to your table files should be relative to the `base_path`. If you use a folder for all your table files you can shorten the path specification by setting the `data_path`. +Default is `.`. Set a default path to the searched directories in order to shorten table filename specifications. -For example, if your table is located in `docs/tables/basic_table.csv`, you can set `data_path` to `docs/tables/` and leave `base_path` to the default `config_dir`. Then you will be able to use \{\{ read_csv("basic_table.csv") \}\} instead of \{\{ read_csv("docs/tables/basic_table.csv") \}\} inside any markdown page. +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`. -Default is `.`, which means you need to specify the path to your table files relative to the `base_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. !!! info @@ -49,24 +32,13 @@ Default is `.`, which means you need to specify the path to your table files rel For more examples see the how to guide on [project structure](howto/project_structure.md). -## `search_page_directory` - -Default: `True`. When enabled, if a filepath is not found, the plugin will also attempt to find the file relative to the current page's directory. - -!!! info - - Note that even when `True`, the path relative to `data_path` is searched first, - and if a file is not found there, then the page's directory is searched. - - For more examples see the how to guide on [project structure](howto/project_structure.md). - ## `allow_missing_files` Default: `False`. When enabled, if a filepath is not found, the plugin will raise a warning instead of an error. ## `select_readers` -Default: Selects all available readers. Specify a list of reader to improve documentation build times for large sites. +Default: Selects all available readers. Specify a list of readers to improve documentation build times for very large sites. ## `enabled` diff --git a/docs/schema.json b/docs/schema.json index 84be7e0..b738606 100644 --- a/docs/schema.json +++ b/docs/schema.json @@ -13,25 +13,12 @@ "markdownDescription": "https://timvink.github.io/mkdocs-table-reader-plugin/options/", "type": "object", "properties": { - "base_path": { - "title": "The base path where mkdocs-table-reader-plugin will search for input files. The path to your table files should be relative to the base_path.", - "markdownDescription": "https://timvink.github.io/mkdocs-table-reader-plugin/options/#base_path", - "type": "string", - "enum": ["config_dir", "docs_dir"], - "default": "config_dir" - }, "data_path": { "title": "The path to your table files should be relative to the base_path. If you use a folder for all your table files you can shorten the path specification by setting the data_path.", "markdownDescription": "https://timvink.github.io/mkdocs-table-reader-plugin/options/#data_path", "type": "string", "default": "." }, - "search_page_directory": { - "title": "When enabled, if a filepath is not found, the plugin will also attempt to find the file relative to the current page's directory.", - "markdownDescription": "https://timvink.github.io/mkdocs-table-reader-plugin/options/#search_page_directory", - "type": "boolean", - "default": true - }, "allow_missing_files": { "title": "When enabled, if a filepath is not found, the plugin will raise a warning instead of an error.", "markdownDescription": "https://timvink.github.io/mkdocs-table-reader-plugin/options/#allow_missing_files", diff --git a/mkdocs.yml b/mkdocs.yml index cdda607..51414a1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,6 +10,7 @@ nav: - How to: - howto/customize_tables.md - howto/preprocess_tables.md + - howto/use_jinja2.md - howto/project_structure.md - howto/docker.md - howto/alternatives.md diff --git a/mkdocs_table_reader_plugin/plugin.py b/mkdocs_table_reader_plugin/plugin.py index b677336..01e6f0a 100644 --- a/mkdocs_table_reader_plugin/plugin.py +++ b/mkdocs_table_reader_plugin/plugin.py @@ -2,7 +2,7 @@ import re import logging -from mkdocs.plugins import BasePlugin +from mkdocs.plugins import BasePlugin, get_plugin_logger from mkdocs.config import config_options from mkdocs.exceptions import ConfigurationError @@ -10,14 +10,13 @@ from mkdocs_table_reader_plugin.readers import READERS from mkdocs_table_reader_plugin.markdown import fix_indentation -logger = logging.getLogger("mkdocs.plugins") +logger = get_plugin_logger("table-reader") + class TableReaderPlugin(BasePlugin): config_scheme = ( - ("base_path", config_options.Choice(['docs_dir','config_dir'], default="config_dir")), ("data_path", config_options.Type(str, default=".")), - ("search_page_directory", config_options.Type(bool, default=True)), ("allow_missing_files", config_options.Type(bool, default=False)), ("select_readers", config_options.ListOfItems(config_options.Choice(list(READERS.keys())), default = list(READERS.keys()))), ) @@ -32,6 +31,11 @@ def on_config(self, config, **kwargs): Returns: Config """ + if "search_page_directory" in self.config: + logger.warning(f"[table-reader]: The 'search_page_directory' configuration option is deprecated, it will always be searched. Please remove it from your mkdocs.yml.") + if "base_path" in self.config: + logger.warning(f"[table-reader]: The 'base_path' configuration option is deprecated. Both the config_dir and docs_dir will be searched. Please remove it from your mkdocs.yml.") + self.readers = {reader: READERS[reader].set_config_context(mkdocs_config=config, plugin_config=self.config) for reader in self.config.get('select_readers') if reader in self.config.get('select_readers',[])} plugins = [p for p in config.get("plugins")] @@ -118,16 +122,14 @@ def on_page_markdown(self, markdown, page, config, files, **kwargs): pd_args, pd_kwargs = parse_argkwarg(result[1]) # Load the table - # note we use the first valid file paths, - # where we first search the 'data_path' and then the page's directory. markdown_table = function(*pd_args, **pd_kwargs) - markdown_table = fix_indentation(leading_spaces, markdown_table) - + # Insert markdown table # By replacing only the first occurrence of the regex pattern # You might insert multiple CSVs with a single reader like read_csv # Because of the replacement, the next occurrence will be the first match for .sub() again. # This is always why when allow_missing_files=True we replaced the input tag. + markdown_table = fix_indentation(leading_spaces, markdown_table) markdown = tag_pattern.sub(markdown_table, markdown, count=1) return markdown diff --git a/tests/fixtures/basic_setup/assets/tables/basic_table2.csv b/tests/fixtures/basic_setup/assets/tables/basic_table2.csv new file mode 100644 index 0000000..46d8995 --- /dev/null +++ b/tests/fixtures/basic_setup/assets/tables/basic_table2.csv @@ -0,0 +1,5 @@ +"a","b" +40,73 +50,52 +531456,80 +"name","table2" \ No newline at end of file