mkdocs-data-plugin 0.1.0__tar.gz → 0.3.0__tar.gz

mkdocs_data_plugin-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Joan Puigcerver
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{mkdocs_data_plugin-0.1.0 → mkdocs_data_plugin-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: mkdocs-data-plugin
-Version: 0.1.0
+Version: 0.3.0
 Summary: MkDocs plugin that allows to read data from markup files
 Project-URL: Documentation, https://joapuiib.github.io/mkdocs-data-plugin
 Project-URL: Download, https://github.com/joapuiib/mkdocs-data-plugin/releases
@@ -8,20 +8,23 @@ Project-URL: Homepage, https://joapuiib.github.io/mkdocs-data-plugin
 Project-URL: Source, https://github.com/joapuiib/mkdocs-data-plugin
 Project-URL: Tracker, https://github.com/joapuiib/mkdocs-data-plugin/issues
 Author-email: Joan Puigcerver <joapuiib@gmail.com>
-License: MIT
+License-Expression: MIT
+License-File: LICENSE
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.8
 Requires-Dist: mkdocs-macros-plugin>=1.2.0
-Requires-Dist: mkdocs>=1.5.2
+Requires-Dist: mkdocs<2.0,>=1.5.2
+Requires-Dist: properdocs>=1.6
 Description-Content-Type: text/markdown
 
 # mkdocs-data-plugin
-MkDocs plugin that allows to read data from markup files
+__MkDocs Data Plugin__ is a plugin for [MkDocs](https://www.mkdocs.org/) that allows
+reading data from markup files and use it in your Markdown pages.
 
 Currently supported formats:
 
-- JSON
-- YAML
+- JSON: `.json`
+- YAML: `.yml`, `.yaml`
 
 ## Documentation
 This plugin documentation can be found here: https://joapuiib.github.io/mkdocs-data-plugin/
@@ -38,5 +41,33 @@ Activate the plugin in your `mkdocs.yml`:
 
 ```yaml
 plugins:
+  - macros
   - data
 ```
+
+## Overview
+When using this plugin, you can define data in YAML or JSON files
+in a separate directory and reference them in your Markdown files.
+
+```txt
+root/
+├── docs/
+│   └── ...
+├── data/
+│   └── fruits.yml
+└── mkdocs.yml
+```
+
+```yaml title="fruits.yml"
+- Apple
+- Banana
+- Strawberry
+```
+
+Files in this directory can be referenced in your Markdown files using the `data` variable.
+
+```markdown
+{% for fruit in data.fruits -%}
+- {{ fruit }}
+{% endfor %}
+```

mkdocs_data_plugin-0.3.0/README.md

@@ -0,0 +1,54 @@
+# mkdocs-data-plugin
+__MkDocs Data Plugin__ is a plugin for [MkDocs](https://www.mkdocs.org/) that allows
+reading data from markup files and use it in your Markdown pages.
+
+Currently supported formats:
+
+- JSON: `.json`
+- YAML: `.yml`, `.yaml`
+
+## Documentation
+This plugin documentation can be found here: https://joapuiib.github.io/mkdocs-data-plugin/
+
+## Installation
+This plugin can be installed via pip:
+
+```bash
+pip install mkdocs-data-plugin
+```
+
+## Configuration
+Activate the plugin in your `mkdocs.yml`:
+
+```yaml
+plugins:
+  - macros
+  - data
+```
+
+## Overview
+When using this plugin, you can define data in YAML or JSON files
+in a separate directory and reference them in your Markdown files.
+
+```txt
+root/
+├── docs/
+│   └── ...
+├── data/
+│   └── fruits.yml
+└── mkdocs.yml
+```
+
+```yaml title="fruits.yml"
+- Apple
+- Banana
+- Strawberry
+```
+
+Files in this directory can be referenced in your Markdown files using the `data` variable.
+
+```markdown
+{% for fruit in data.fruits -%}
+- {{ fruit }}
+{% endfor %}
+```

mkdocs_data_plugin-0.3.0/mkdocs_data_plugin/__init__.py

@@ -0,0 +1,5 @@
+import properdocs.replacement_warning
+
+properdocs.replacement_warning.setup()
+
+version = "0.3.0"

mkdocs_data_plugin-0.3.0/mkdocs_data_plugin/plugin.py

@@ -0,0 +1,88 @@
+import json
+import os
+
+import yaml
+from mkdocs.config import base
+from mkdocs.config import config_options as c
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.plugins import BasePlugin, get_plugin_logger
+
+log = get_plugin_logger(__name__)
+
+
+class DataPluginConfig(base.Config):
+    sources = c.Type(dict, default={'data': 'data'})
+
+
+class DataPlugin(BasePlugin[DataPluginConfig]):
+    def __init__(self):
+        self.sources = {}
+        self.processors = {'.yml': yaml.safe_load, '.yaml': yaml.safe_load, '.json': json.load}
+
+    def load_sources(self):
+        """
+        Load all sources from the config file and load the data from the files.
+        """
+        for source, path in self.config['sources'].items():
+            if not os.path.exists(path):
+                log.warning(f"Mapping path '{path}' not found. Skipping.")
+            elif os.path.isdir(path):
+                self.load_folder(source, path)
+            else:
+                value = self.load_file(path)
+                self.update_data(source, [], value)
+
+    def update_data(self, source: str, keys: list, value: any):
+        """
+        Update the sources data with the given value.
+        """
+        if len(keys) == 0:
+            self.sources[source] = value
+        else:
+            data = self.sources.setdefault(source, {})
+            for key in keys[:-1]:
+                data = data.setdefault(key, {})
+            data[keys[-1]] = value
+
+    def load_folder(self, source: str, path: str):
+        """
+        Iterate over all files in the data directory
+        and load them into the data attribute.
+        """
+        for root, _, files in os.walk(path):
+
+            keys = []
+            if root != path:
+                directory = os.path.relpath(root, path)
+                keys = directory.split(os.sep)
+
+            for file in files:
+                value = self.load_file(os.path.join(root, file))
+
+                filename, _ = os.path.splitext(file)
+                self.update_data(source, keys + [filename], value)
+
+    def load_file(self, path: str):
+        """
+        Loads a file and processes it with the appropriate processor.
+        """
+        _, extension = os.path.splitext(path)
+        with open(path, 'r') as file:
+            return self.processors[extension](file)
+
+    def on_config(self, config: MkDocsConfig):
+        self.load_sources()
+
+        macros_plugin = config.plugins.get('macros')
+        if macros_plugin:
+            for source, data in self.sources.items():
+                macros_plugin.register_variables({source: data})
+        else:
+            log.warning(
+                "The macros plugin is not installed. The `data` variable won't be available in pages."
+            )
+
+    def on_page_context(self, context, page, config, nav):
+        for source, data in self.sources.items():
+            context[source] = data
+        return context

{mkdocs_data_plugin-0.1.0 → mkdocs_data_plugin-0.3.0}/pyproject.toml

@@ -16,7 +16,8 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 dependencies = [
-    "mkdocs>=1.5.2",
+    "mkdocs>=1.5.2,<2.0",
+    "properdocs>=1.6",
     "mkdocs-macros-plugin>=1.2.0",
 ]
 
@@ -63,12 +64,17 @@ type = ["default"]
 
 [tool.hatch.envs.doc]
 dependencies = [
-    "mkdocs-material>=9.2.5"
+    "mkdocs-materialx[imaging]~=10.1",
+    "mkdocs-alias-plugin~=0.8",
+    "mkdocs-git-revision-date-localized-plugin~=1.2",
 ]
 
 [tool.hatch.envs.doc.scripts]
 serve = [
-    "mkdocs serve",
+    "properdocs serve",
+]
+build = [
+    "properdocs build",
 ]
 
 [tool.hatch.envs.style]
@@ -81,13 +87,13 @@ dependencies = [
 
 [tool.hatch.envs.style.scripts]
 check = [
-    "isort --check-only --diff mkdocs_static_i18n",
-    "black -q --check --diff mkdocs_static_i18n",
-    "ruff check mkdocs_static_i18n",
+    "isort --check-only --diff mkdocs_data_plugin",
+    "black -q --check --diff mkdocs_data_plugin",
+    "ruff check mkdocs_data_plugin",
 ]
 format = [
-    "isort -q mkdocs_static_i18n",
-    "black -q mkdocs_static_i18n",
+    "isort -q mkdocs_data_plugin",
+    "black -q mkdocs_data_plugin",
 ]
 
 [tool.black]

mkdocs_data_plugin-0.3.0/tests/data/a.yml

@@ -0,0 +1,2 @@
+number: 1
+string: text

mkdocs_data_plugin-0.3.0/tests/data/dir1/b.yml

@@ -0,0 +1,2 @@
+number: 2
+string: text

mkdocs_data_plugin-0.3.0/tests/data/dir1.yml

@@ -0,0 +1,2 @@
+number: 1
+string: text

mkdocs_data_plugin-0.3.0/tests/data/dir2/c.json

@@ -0,0 +1,4 @@
+{
+  "number": 3,
+  "string": "text"
+}

mkdocs_data_plugin-0.3.0/tests/docs/fruits.yml

@@ -0,0 +1,3 @@
+- Apple
+- Banana
+- Strawberry

mkdocs_data_plugin-0.3.0/tests/docs/test_dir_source.md

@@ -0,0 +1,11 @@
+---
+title: "Test Directory Source"
+---
+
+- data.a: `{{ data.a }}`
+- data.a.number: `{{ data.a.number }}`
+- data.a.string: `{{ data.a.string }}`
+- data.dir1.b.number: `{{ data.dir1.b.number }}`
+- data.dir1.b.string: `{{ data.dir1.b.string }}`
+- data.dir2.c.number: `{{ data.dir2.c.number }}`
+- data.dir2.c.string: `{{ data.dir2.c.string }}`

mkdocs_data_plugin-0.3.0/tests/docs/test_file_source.md

@@ -0,0 +1,7 @@
+---
+title: "Test File Source"
+---
+
+{% for fruit in fruits %}
+- `{{ fruit }}`
+{% endfor %}

{mkdocs_data_plugin-0.1.0 → mkdocs_data_plugin-0.3.0}/tests/test_config.py

@@ -6,10 +6,10 @@ from mkdocs_data_plugin.plugin import DataPlugin
 def test_config_default_values():
     plugin = DataPlugin()
     plugin.load_config({})
-    assert plugin.config.data_dir == 'data'
+    assert plugin.config.sources == {'data': 'data'}
 
 
-def test_config_data_dir():
+def test_config_sources():
     plugin = DataPlugin()
-    plugin.load_config({'data_dir': 'other_data'})
-    assert plugin.config.data_dir == 'other_data'
+    plugin.load_config({'sources': {'data': 'other_data'}})
+    assert plugin.config.sources == {'data': 'other_data'}

mkdocs_data_plugin-0.3.0/tests/test_data_template.py

@@ -0,0 +1,52 @@
+import re
+
+from mkdocs.commands.build import build
+from mkdocs.config.base import load_config
+
+
+def test_dir_source_in_markdown_file():
+    mkdocs_config = load_config(
+        "tests/mkdocs.yml",
+        plugins={
+            "macros": {},
+            "data": {'sources': {'data': 'tests/data'}},
+        },
+    )
+
+    build(mkdocs_config)
+    site_dir = mkdocs_config["site_dir"]
+
+    with open(site_dir+'/test_dir_source/index.html') as f:
+        data_loaded = re.findall(r"<code>([^<]*)", f.read())
+        print(data_loaded)
+        assert(data_loaded == [
+            "{'number': 1, 'string': 'text'}", # data/a.yml
+            "1", # data/a.yml -> number
+            "text", # data/a.yml -> string
+            "2", # data/dir1/b.yml -> number
+            "text", # data/dir1/b.yml -> string
+            "3", # data/dir2/c.yml -> number
+            "text", # data/dir2/c.yml -> string
+        ])
+
+def test_file_source_in_markdown_file():
+    mkdocs_config = load_config(
+        "tests/mkdocs.yml",
+        plugins={
+            "macros": {},
+            "data": {'sources': {'fruits': 'tests/docs/fruits.yml'}},
+        },
+    )
+
+    build(mkdocs_config)
+    site_dir = mkdocs_config["site_dir"]
+
+    with open(site_dir+'/test_file_source/index.html') as f:
+        data_loaded = re.findall(r"<code>([^<]*)", f.read())
+        print(data_loaded)
+        assert(data_loaded == [
+            "Apple",
+            "Banana",
+            "Strawberry",
+        ])
+

mkdocs_data_plugin-0.3.0/tests/test_load_data.py

@@ -0,0 +1,102 @@
+from mkdocs.commands.build import build
+from mkdocs.config.base import load_config
+
+
+def test_inexistent_source_is_skipped():
+    mkdocs_config = load_config(
+        "tests/mkdocs.yml",
+        plugins={
+            "data": {'sources': {'data': 'tests/inexistent'}}
+        },
+    )
+
+    build(mkdocs_config)
+
+    dataPlugin = mkdocs_config["plugins"]["data"]
+
+    assert "data" not in dataPlugin.sources
+
+
+def test_folder_source():
+    mkdocs_config = load_config(
+        "tests/mkdocs.yml",
+        plugins={
+            "data": {'sources': {'data': 'tests/data'}}
+        },
+    )
+
+    build(mkdocs_config)
+
+    dataPlugin = mkdocs_config["plugins"]["data"]
+    data = dataPlugin.sources["data"]
+
+    assert data == {
+            "a": {
+                "number": 1,
+                "string": "text",
+            },
+            "dir1": {
+                "number": 1,
+                "string": "text",
+                "b": {
+                    "number": 2,
+                    "string": "text",
+                },
+            },
+            "dir2": {
+                "c": {
+                    "number": 3,
+                    "string": "text",
+                },
+            },
+    }
+
+def test_folder_source_slash():
+    mkdocs_config = load_config(
+        "tests/mkdocs.yml",
+        plugins={
+            "data": {'sources': {'data': 'tests/data/'}}
+        },
+    )
+
+    build(mkdocs_config)
+
+    dataPlugin = mkdocs_config["plugins"]["data"]
+    data = dataPlugin.sources["data"]
+
+    assert data == {
+            "a": {
+                "number": 1,
+                "string": "text",
+            },
+            "dir1": {
+                "number": 1,
+                "string": "text",
+                "b": {
+                    "number": 2,
+                    "string": "text",
+                },
+            },
+            "dir2": {
+                "c": {
+                    "number": 3,
+                    "string": "text",
+                },
+            },
+    }
+
+def test_file_source():
+    mkdocs_config = load_config(
+        "tests/mkdocs.yml",
+        plugins={
+            "data": {'sources': {'fruits': 'tests/docs/fruits.yml'}}
+        },
+    )
+
+    build(mkdocs_config)
+
+    dataPlugin = mkdocs_config["plugins"]["data"]
+    data = dataPlugin.sources["fruits"]
+    print(dataPlugin.sources)
+
+    assert data == ['Apple', 'Banana', 'Strawberry']

mkdocs_data_plugin-0.1.0/README.md

@@ -1,25 +0,0 @@
-# mkdocs-data-plugin
-MkDocs plugin that allows to read data from markup files
-
-Currently supported formats:
-
-- JSON
-- YAML
-
-## Documentation
-This plugin documentation can be found here: https://joapuiib.github.io/mkdocs-data-plugin/
-
-## Installation
-This plugin can be installed via pip:
-
-```bash
-pip install mkdocs-data-plugin
-```
-
-## Configuration
-Activate the plugin in your `mkdocs.yml`:
-
-```yaml
-plugins:
-  - data
-```

mkdocs_data_plugin-0.1.0/mkdocs_data_plugin/__init__.py

@@ -1,2 +0,0 @@
-version = "0.1.0"
-__version__ = "0.1.0"

mkdocs_data_plugin-0.1.0/mkdocs_data_plugin/plugin.py

@@ -1,78 +0,0 @@
-import os
-import yaml
-import json
-
-
-from mkdocs.config.defaults import MkDocsConfig
-from mkdocs.config import base, config_options as c
-from mkdocs.plugins import BasePlugin, get_plugin_logger
-
-log = get_plugin_logger(__name__)
-
-class DataPluginConfig(base.Config):
-    data_dir = c.Type(str, default='data')
-
-
-class DataPlugin(BasePlugin[DataPluginConfig]):
-    def __init__(self):
-        self.data = {}
-        self.processors = {
-            '.yml': yaml.safe_load,
-            '.yaml': yaml.safe_load,
-            '.json': json.load
-        }
-
-
-    def set_data(self, keys, value):
-        """
-        Set a value in the data attribute.
-        """
-        data = self.data
-        for key in keys[:-1]:
-            data = data.setdefault(key, {})
-        data[keys[-1]] = value
-
-
-    def on_config(self, config: MkDocsConfig):
-        self.load_data(self.config.data_dir)
-
-        macros_plugin = config.plugins.get('macros')
-        if macros_plugin:
-            macros_plugin.register_variables({'data': self.data})
-        else:
-            log.warning("The macros plugin is not installed. The `data` variable won't be available in pages.")
-
-
-    def load_data(self, path: str):
-        """
-        Iterate over all files in the data directory
-        and load them into the data attribute.
-        """
-        for root, _, files in os.walk(path):
-
-            keys = []
-            if root != self.config.data_dir:
-                directory = os.path.relpath(root, self.config.data_dir)
-                keys = directory.split(os.sep)
-
-            for file in files:
-                value = self.load_file(os.path.join(root, file))
-
-                filename, _ = os.path.splitext(file)
-                self.set_data(keys + [filename], value)
-
-
-    def load_file(self, path: str):
-        """
-        Load a file and return its content.
-        """
-        _, extension = os.path.splitext(path)
-        with open(path, 'r') as file:
-            return self.processors[extension](file)
-
-
-
-    def on_page_context(self, context, page, config, nav):
-        context['data'] = self.data
-        return context
-

mkdocs_data_plugin-0.1.0/tests/data/a.yml

@@ -1,2 +0,0 @@
-a1: 1
-a2: text

mkdocs_data_plugin-0.1.0/tests/data/dir1/b.yml

@@ -1,2 +0,0 @@
-b1: 2
-b2: text

mkdocs_data_plugin-0.1.0/tests/data/dir2/c.json

@@ -1,4 +0,0 @@
-{
-  "c1": 3,
-  "c2": "text"
-}

mkdocs_data_plugin-0.1.0/tests/docs/test_data_template.md

@@ -1,11 +0,0 @@
----
-title: "Test Data Template"
----
-
-- data.a: `{{ data.a }}`
-- data.a.a1: `{{ data.a.a1 }}`
-- data.a.a2: `{{ data.a.a2 }}`
-- data.dir1.b.b1: `{{ data.dir1.b.b1 }}`
-- data.dir1.b.b2: `{{ data.dir1.b.b2 }}`
-- data.dir2.c.c1: `{{ data.dir2.c.c1 }}`
-- data.dir2.c.c2: `{{ data.dir2.c.c2 }}`

mkdocs_data_plugin-0.1.0/tests/test_data_template.py

@@ -1,31 +0,0 @@
-import re
-
-from mkdocs.commands.build import build
-from mkdocs.config.base import load_config
-
-
-def test_loads_files():
-    mkdocs_config = load_config(
-        "tests/mkdocs.yml",
-        plugins={
-            "macros": {},
-            "data": {'data_dir': 'tests/data'},
-        },
-    )
-
-    build(mkdocs_config)
-    site_dir = mkdocs_config["site_dir"]
-
-    with open(site_dir+'/test_data_template/index.html') as f:
-        data_loaded = re.findall(r"<code>([^<]*)", f.read())
-        print(data_loaded)
-        assert(data_loaded == [
-            "{'a1': 1, 'a2': 'text'}", # data/a.yml
-            "1", # data/a.yml -> a1
-            "text", # data/a.yml -> a2
-            "2", # data/dir1/b.yml -> b1
-            "text", # data/dir1/b.yml -> b2
-            "3", # data/dir2/c.yml -> c1
-            "text", # data/dir2/c.yml -> c2
-        ])
-

mkdocs_data_plugin-0.1.0/tests/test_load_data.py

@@ -1,51 +0,0 @@
-from mkdocs.commands.build import build
-from mkdocs.config.base import load_config
-
-
-def test_empty_data_is_empty_dict():
-    mkdocs_config = load_config(
-        "tests/mkdocs.yml",
-        plugins={
-            "data": {'data_dir': 'tests/inexistent'}
-        },
-    )
-
-    build(mkdocs_config)
-
-    dataPlugin = mkdocs_config["plugins"]["data"]
-    data = dataPlugin.data
-
-    assert data == {}
-
-
-def test_loads_files():
-    mkdocs_config = load_config(
-        "tests/mkdocs.yml",
-        plugins={
-            "data": {'data_dir': 'tests/data'}
-        },
-    )
-
-    build(mkdocs_config)
-
-    dataPlugin = mkdocs_config["plugins"]["data"]
-    data = dataPlugin.data
-
-    assert data == {
-            "a": {
-                "a1": 1,
-                "a2": "text",
-            },
-            "dir1": {
-                "b": {
-                    "b1": 2,
-                    "b2": "text",
-                },
-            },
-            "dir2": {
-                "c": {
-                    "c1": 3,
-                    "c2": "text",
-                },
-            },
-    }