Update docs and add deprecation warnings

CONTRIBUTING.md

@@ -49,4 +49,18 @@ git tag <version>
 git push origin <version>
 ```
 
-Then manually create a github release to trigger publishing to pypi.
+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
+

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.
 

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:
+
+- <code>\{\{ read_csv("docs/folder/another_table.csv") \}\}</code> (Path relative to mkdocs.yml)
+- <code>\{\{ read_csv("folder/another_table.csv") \}\}</code> (Path relative to docs/ directory)
+- <code>\{\{ read_csv("another_table.csv") \}\}</code> (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:
-
-- <code>\{\{ read_csv("docs/assets/tables/another_table.csv") \}\}</code> when `base_path` [option](../options.md) is set to `config_dir` (default)
-- <code>\{\{ read_csv("assets/tables/another_table.csv") \}\}</code> when `base_path` [option](../options.md) is set to `docs_dir`
-- <code>\{\{ read_csv("../another_table.csv") \}\}</code> 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:
-
-- <code>\{\{ read_csv("docs/tables/basic_table.csv") \}\}</code> when `base_path` [option](../options.md) is set to `config_dir` (default)
-- <code>\{\{ read_csv("tables/basic_table.csv") \}\}</code> when `base_path` [option](../options.md) is set to `docs_dir`
-- <code>\{\{ read_csv("basic_table.csv") \}\}</code> 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:
 
-- <code>\{\{ read_csv("docs/folder/another_table.csv") \}\}</code> when `base_path` is set to `config_dir` (default)
-- <code>\{\{ read_csv("folder/another_table.csv") \}\}</code> when `base_path` is set to `docs_dir`
-- <code>\{\{ read_csv("another_table.csv") \}\}</code> 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`
+- <code>\{\{ read_csv("docs/assets/tables/another_table.csv") \}\}</code> (Path relative to mkdocs.yml)
+- <code>\{\{ read_csv("assets/tables/another_table.csv") \}\}</code> (Path relative to docs/ directory)
+- <code>\{\{ read_csv("../assets/tables/another_table.csv") \}\}</code> (Path relative to page source file _(note that `..` stands for "one directory up")_)
+

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 %}
+
+```

docs/options.md

@@ -10,63 +10,35 @@ 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
         - read_json
       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 <code>\{\{ read_csv("docs/assets/table.csv") \}\}</code>, or when `base_path` is `docs_dir`, with <code>\{\{ read_csv("assets/table.csv") \}\}</code>.
-
-!!! 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 <code>\{\{ read_csv("basic_table.csv") \}\}</code> instead of <code>\{\{ read_csv("docs/tables/basic_table.csv") \}\}</code> 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 <code>\{\{ read_csv("basic_table.csv") \}\}</code> instead of <code>\{\{ read_csv("docs/assets/tables/basic_table.csv") \}\}</code> inside any markdown page.
 
 !!! 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).
 
-## `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`
 

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",

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

mkdocs_table_reader_plugin/plugin.py

@@ -2,22 +2,21 @@
 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
 
 from mkdocs_table_reader_plugin.safe_eval import parse_argkwarg
 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

tests/fixtures/basic_setup/assets/tables/basic_table2.csv

@@ -0,0 +1,5 @@
+"a","b"
+40,73
+50,52
+531456,80
+"name","table2"