Add tested support for mkdocstrings plugin

mondeja · Jun 9, 2021 · 7f0af84 · 7f0af84
1 parent aa1a795
commit 7f0af84
Show file tree

Hide file tree

Showing 10 changed files with 156 additions and 52 deletions.
diff --git a/.bumpversion.cfg b/.bumpversion.cfg
@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.0.9
+current_version = 0.0.10
 
 [bumpversion:file:mkdocs_mdpo_plugin/__init__.py]
 

diff --git a/docs/es/tested-plugins/api-documentation-building.md.po b/docs/es/tested-plugins/api-documentation-building.md.po
@@ -0,0 +1,16 @@
+#
+msgid ""
+msgstr ""
+
+msgid "API documentation building"
+msgstr "Construcción de documentación de API"
+
+msgid "[API documentation building][api-documentation-building]"
+msgstr "[Construcción de documentación de API][api-documentation-building]"
+
+msgid ""
+"[api-documentation-building]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-"
+"Plugins#api-documentation-building"
+msgstr ""
+"[api-documentation-building]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-"
+"Plugins#api-documentation-building"
diff --git a/docs/tested-plugins/api-documentation-building.md b/docs/tested-plugins/api-documentation-building.md
@@ -0,0 +1,8 @@
+# [API documentation building][api-documentation-building]
+
+<!-- mdpo-disable -->
+- [x] [mkdocstrings](https://github.com/pawamoy/mkdocstrings)
+
+<!-- mdpo-enable -->
+
+[api-documentation-building]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins#api-documentation-building
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -28,6 +28,7 @@ nav:
       - PyMdown extensions: extensions-support/pymdownx.md
   - Tested plugins:
       - Navigation and page building: tested-plugins/navigation-and-page-building.md
+      - API documentation building: tested-plugins/api-documentation-building.md
 
 markdown_extensions:
   - toc:
@@ -67,6 +68,13 @@ plugins:
   - exclude:
       glob:
         - file-to-be-inserted.txt
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          rendering:
+            show_source: false
+            show_root_toc_entry: false
   - mdpo:
       relative_material_language_selector: true
   - minify:

diff --git a/mkdocs_mdpo_plugin/__init__.py b/mkdocs_mdpo_plugin/__init__.py
@@ -1,3 +1,3 @@
 """mkdocs-mdpo-plugin package"""
 
-__version__ = '0.0.9'
+__version__ = '0.0.10'
diff --git a/mkdocs_mdpo_plugin/mdpo_events.py b/mkdocs_mdpo_plugin/mdpo_events.py
@@ -21,24 +21,15 @@
     from pymdownx.tabbed import TabbedProcessor  # noqa: F401
 except ImportError:  # pragma: no cover
     pass
+try:
+    from mkdocstrings.extension import (  # noqa: F401
+        AutoDocProcessor as MkDocsStringsProcessor,
+        MkdocstringsExtension,
+    )
+except ImportError:  # pragma: no cover
+    pass
 
 
-MD2PO_EVENT_EXTENSIONS = {
-    'text': [
-        'admonition',
-        'def_list',
-        'pymdownx.details',
-        'pymdownx.snippets',
-        'pymdownx.tabbed',
-    ],
-    'msgid': [
-        'def_list',
-    ],
-    'link_reference': [
-        'footnotes',
-    ],
-}
-
 PO2MD_EVENT_EXTENSIONS = {
     'link_reference': [
         'footnotes',
@@ -47,7 +38,17 @@
 
 
 def build_md2po_events(mkdocs_build_config):
-    md_extensions = mkdocs_build_config['markdown_extensions']
+    _md_extensions = mkdocs_build_config['markdown_extensions']
+
+    md_extensions = []
+    for ext in _md_extensions:
+        if not isinstance(ext, str):
+            if isinstance(ext, MkdocstringsExtension):
+                md_extensions.append('mkdocstrings')
+            else:
+                md_extensions.append(ext)
+        else:
+            md_extensions.append(ext)
 
     def build_event(event_type):
         parameters = {
@@ -64,6 +65,7 @@ def build_event(event_type):
                     're.match(SnippetPreprocessor.RE_ALL_SNIPPETS, text)'
                 ),
                 'pymdownx.tabbed': 're.match(TabbedProcessor.START, text)',
+                'mkdocstrings': 're.match(MkDocsStringsProcessor.regex, text)',
             }
 
             body = ''

diff --git a/mkdocs_mdpo_plugin/plugin.py b/mkdocs_mdpo_plugin/plugin.py
@@ -13,6 +13,7 @@
 from mdpo.md2po import Md2Po
 from mdpo.md4c import DEFAULT_MD4C_GENERIC_PARSER_EXTENSIONS
 from mdpo.po2md import Po2Md
+from mkdocs.config.config_options import Type
 
 from mkdocs_mdpo_plugin.io import (
     remove_empty_directories_from_dirtree,
@@ -78,40 +79,16 @@ def instance(cls, mdpo_plugin):
 
 class MdpoPlugin(mkdocs.plugins.BasePlugin):
     config_scheme = (
-        (
-            'locale_dir',
-            mkdocs.config.config_options.Type(str, default=''),
-        ),
-        (
-            'default_language',
-            mkdocs.config.config_options.Type(str, required=False),
-        ),
-        (
-            'languages',
-            mkdocs.config.config_options.Type(list, required=False),
-        ),
-        (
-            'lc_messages',
-            mkdocs.config.config_options.Type((str, bool), default=''),
-        ),
+        ('locale_dir', Type(str, default='')),
+        ('default_language', Type(str, required=False)),
+        ('languages', Type(list, required=False)),
+        ('lc_messages', Type((str, bool), default='')),
         (
             'dest_filename_template',
-            mkdocs.config.config_options.Type(
-                str,
-                default='{{language}}/{{page.file.dest_path}}',
-            ),
-        ),
-        (
-            'ignore_extensions',
-            mkdocs.config.config_options.Type(
-                list,
-                default=['.po', '.pot', '.mo'],
-            ),
-        ),
-        (
-            'relative_material_language_selector',
-            mkdocs.config.config_options.Type(bool, default=False),
+            Type(str, default='{{language}}/{{page.file.dest_path}}'),
         ),
+        ('ignore_extensions', Type(list, default=['.po', '.pot', '.mo'])),
+        ('relative_material_language_selector', Type(bool, default=False)),
     )
 
     def __init__(self, *args, **kwargs):

diff --git a/setup.cfg b/setup.cfg
@@ -1,6 +1,6 @@
 [metadata]
 name = mkdocs_mdpo_plugin
-version = 0.0.9
+version = 0.0.10
 description = Mkdocs plugin for translations using PO files.
 long_description = file: README.md
 long_description_content_type = text/markdown
@@ -48,6 +48,7 @@ dev =
     mkdocs-exclude==1.0.2
     mkdocs-include-markdown-plugin==3.1.0
     mkdocs-material==7.1.2
+    mkdocstrings==0.15.1
     pre-commit==2.12.1
     pymdown-extensions==8.1.1
     pytest==6.2.3
@@ -59,6 +60,7 @@ doc =
     mkdocs-include-markdown-plugin==3.1.0
     mkdocs-material==7.1.2
     mkdocs-minify-plugin==0.4.0
+    mkdocstrings==0.15.1
     pymdown-extensions==8.1.1
 lint =
     flake8==3.9.1
@@ -70,6 +72,7 @@ test =
     mkdocs==1.1.2
     mkdocs-exclude==1.0.2
     mkdocs-material==7.1.2
+    mkdocstrings==0.15.1
     pymdown-extensions==8.1.1
     pytest==6.2.3
     pytest-cov==2.11.1

diff --git a/tests/test_plugins/test_api_documentation_building.py b/tests/test_plugins/test_api_documentation_building.py
@@ -0,0 +1,90 @@
+"""Mkdocs builds tests for mkdocs-mdpo-plugin API documentation building
+plugins support:
+https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins#api-documentation-building
+"""
+
+import pytest
+
+
+TESTS = (
+    pytest.param(  # mkdocstrings (configuration before mdpo)
+        {
+            'index.md': (
+                'Hello\n\n::: mkdocs_mdpo_plugin.io.'
+                'remove_empty_directories_from_dirtree\n\nBye'
+            ),
+        },
+        {
+            'es/index.md.po': {
+                'Hello': 'Hola',
+                'Bye': 'Adios',
+                (
+                    'Remove empty directories walking through all nested'
+                    ' subdirectories.'
+                ): (
+                 'Elimina directorios vacíos caminando'
+                 ' por todos los subdirectorios anidados.'
+                ),
+                'Top directory tree path.': (
+                    'Path al directorio superior en el árbol.'
+                ),
+            },
+        },
+        {
+            'languages': ['en', 'es'],
+        },
+        {
+            'plugins': [
+                {
+                    'mkdocstrings': {},
+                },
+            ],
+        },
+        {
+            'index.html': [
+                '<p>Hello</p>',
+                (
+                    '<p>Remove empty directories walking through all nested'
+                    ' subdirectories.</p>'
+                ),
+                '<td><p>Top directory tree path.</p></td>',
+            ],
+            'es/index.html': [
+                '<p>Hola</p>',
+                (
+                    '<p>Elimina directorios vacíos caminando por todos'
+                    ' los subdirectorios anidados.</p>'
+                ),
+                '<td><p>Path al directorio superior en el árbol.</p></td>',
+            ],
+        },
+        id='mkdocs-exclude (before mdpo)',
+    ),
+)
+
+
+@pytest.mark.parametrize(
+    (
+        'input_files_contents',
+        'translations',
+        'plugin_config',
+        'additional_config',
+        'expected_output_files',
+    ),
+    TESTS,
+)
+def test_navigation_and_page_building_plugins(
+    input_files_contents,
+    translations,
+    plugin_config,
+    additional_config,
+    expected_output_files,
+    mkdocs_build,
+):
+    mkdocs_build(
+        input_files_contents,
+        translations,
+        plugin_config,
+        additional_config,
+        expected_output_files,
+    )
diff --git a/tests/test_plugins/test_navigation_and_page_building.py b/tests/test_plugins/test_navigation_and_page_building.py
@@ -1,6 +1,6 @@
 """Mkdocs builds tests for mkdocs-mdpo-plugin Navigation and page building
 plugins support:
-https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins#navigation--page-building)
+https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins#navigation--page-building
 """
 
 import os