From 7f0af84096b17cdb6e2b9ede3fb07dbb79ff7646 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=81lvaro=20Mond=C3=A9jar=20Rubio?= Date: Wed, 9 Jun 2021 23:28:37 +0200 Subject: [PATCH] Add tested support for mkdocstrings plugin --- .bumpversion.cfg | 2 +- .../api-documentation-building.md.po | 16 ++++ .../api-documentation-building.md | 8 ++ mkdocs.yml | 8 ++ mkdocs_mdpo_plugin/__init__.py | 2 +- mkdocs_mdpo_plugin/mdpo_events.py | 36 ++++---- mkdocs_mdpo_plugin/plugin.py | 39 ++------ setup.cfg | 5 +- .../test_api_documentation_building.py | 90 +++++++++++++++++++ .../test_navigation_and_page_building.py | 2 +- 10 files changed, 156 insertions(+), 52 deletions(-) create mode 100644 docs/es/tested-plugins/api-documentation-building.md.po create mode 100644 docs/tested-plugins/api-documentation-building.md create mode 100644 tests/test_plugins/test_api_documentation_building.py diff --git a/.bumpversion.cfg b/.bumpversion.cfg index a300cba..6a1b429 100644 --- 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 new file mode 100644 index 0000000..136fc69 --- /dev/null +++ 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 new file mode 100644 index 0000000..d77e706 --- /dev/null +++ b/docs/tested-plugins/api-documentation-building.md @@ -0,0 +1,8 @@ +# [API documentation building][api-documentation-building] + + +- [x] [mkdocstrings](https://github.com/pawamoy/mkdocstrings) + + + +[api-documentation-building]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins#api-documentation-building diff --git a/mkdocs.yml b/mkdocs.yml index c1844fa..0426fb2 100644 --- 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 index 9fc0dbb..d71c888 100644 --- 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 index 8f05c13..f056cd4 100644 --- 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 index fc8ff87..6727f7c 100644 --- 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 index 21efcf8..941dc09 100644 --- 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 new file mode 100644 index 0000000..e26f10d --- /dev/null +++ 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': [ + '

Hello

', + ( + '

Remove empty directories walking through all nested' + ' subdirectories.

' + ), + '

Top directory tree path.

', + ], + 'es/index.html': [ + '

Hola

', + ( + '

Elimina directorios vacíos caminando por todos' + ' los subdirectorios anidados.

' + ), + '

Path al directorio superior en el árbol.

', + ], + }, + 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 index d98cf73..04845f5 100644 --- 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