From 82b77726d7dd9781625bfb11253766abe489bcc8 Mon Sep 17 00:00:00 2001 From: Dylann Cordel Date: Wed, 13 Sep 2023 12:56:35 +0200 Subject: [PATCH] improve-doc --- docs/source/api.md | 44 ++++++++++++++++++++++++++ docs/source/index.md | 2 ++ pyproject.toml | 1 + setup.cfg | 2 +- wagtail_parler/forms.py | 14 ++++++--- wagtail_parler/handlers.py | 63 +++++++++++++++++++++++++++++++++++++- 6 files changed, 119 insertions(+), 7 deletions(-) create mode 100644 docs/source/api.md diff --git a/docs/source/api.md b/docs/source/api.md new file mode 100644 index 0000000..f8ccce8 --- /dev/null +++ b/docs/source/api.md @@ -0,0 +1,44 @@ +# API documentation + +## ParlerAdminWagtailMixin (internal use) + +**⚠️ This mixin is documented for dev only: you SHOULD NOT use it directly ⚠️** + +```{eval-rst} +.. autoclass:: wagtail_parler.handlers.ParlerAdminWagtailMixin + :members: + :undoc-members: + :show-inheritance: +``` + +## ParlerSnippetAdminMixin + +```{eval-rst} +.. autoclass:: wagtail_parler.handlers.ParlerSnippetAdminMixin + :members: + :undoc-members: + :show-inheritance: +``` + + +## ParlerModelAdminMixin + +```{eval-rst} +.. autoclass:: wagtail_parler.handlers.ParlerModelAdminMixin + :members: + :undoc-members: + :show-inheritance: + +``` + +## AutoParlerModelForm + +**⚠️ This class is documented for dev only: you SHOULD NOT use it directly ⚠️** + +```{eval-rst} +.. autoclass:: wagtail_parler.forms.AutoParlerModelForm + :members: + :undoc-members: + :show-inheritance: + +``` diff --git a/docs/source/index.md b/docs/source/index.md index 3be75e7..fdd1d07 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -1,8 +1,10 @@ ```{include} presentation.md ``` + ```{toctree} :maxdepth: 2 presentation configuration usage +api ``` diff --git a/pyproject.toml b/pyproject.toml index 2fbae51..e015310 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -12,6 +12,7 @@ | migrations | \.tox | \.venv + | docs/\.*/ )/ ''' diff --git a/setup.cfg b/setup.cfg index 0a27aac..3ad5813 100644 --- a/setup.cfg +++ b/setup.cfg @@ -46,7 +46,7 @@ testing = types-requests [flake8] -exclude = build,.git,.tox,./wagtail_parler_tests/.env,./.venv,./wagtail_parler_tests/settings.py +exclude = build,.git,.tox,./wagtail_parler_tests/.env,./.venv,docs/.*/,./wagtail_parler_tests/settings.py max-line-length = 99 [black] diff --git a/wagtail_parler/forms.py b/wagtail_parler/forms.py index ef8e1b1..144c7c6 100644 --- a/wagtail_parler/forms.py +++ b/wagtail_parler/forms.py @@ -69,15 +69,19 @@ def _save_locale(self, locale: str) -> Tuple: """ Depending sent data, will save/create/delete translation for the given language code - param: locale: str: locale code of translation to save/create/delete - return: (None|True|False, int|instance|[instances]: - for deletion, will return None and the number of translations deleted - for creation, will return True and the created of translation - for update, will return False and the updated of translation + Args: + locale (str): locale code of translation to save/create/delete + + Returns: + (None|True|False, int|instance|[instances]: for deletion, will return None and the + number of translations deleted + for creation, will return True and the created of translation + for update, will return False and the updated of translation """ obj = self.instance # type: ignore trans_exists = obj.has_translation(locale) data = self.cleaned_data_for_locales.get(locale) + if not data or all(not d for d in data.values()): return None, obj.delete_translation(locale) if trans_exists else 0 return ( diff --git a/wagtail_parler/handlers.py b/wagtail_parler/handlers.py index 6508a72..a000ff8 100644 --- a/wagtail_parler/handlers.py +++ b/wagtail_parler/handlers.py @@ -89,6 +89,8 @@ def get_bound_panel( class ParlerAdminWagtailMixin: """ Mixin to manage translations via Parler inside a ModelAdmin or SnippetViewSet + + You **SHOULD NOT** use this Mixin directly but ParlerModelAdminMixin or ParlerSnippetAdminMixin """ def _set_translations_handlers( @@ -162,9 +164,68 @@ def get_edit_handler(self: ModelAdmin) -> TabbedInterface: class ParlerModelAdminMixin(ParlerAdminWagtailMixin): - pass + """ + Mixin to use with ModelAdmin to manage parler translations. + ex: + + .. code-block:: python + + class SomeModelAdmin(ParlerModelAdminMixin, ModelAdmin): + model = SomeModel + + + class FoodModelAdmin(ParlerModelAdminMixin, ModelAdmin): + model = Food + edit_handler = ObjectList( + children=[ + FieldPanel("yum_rating"), + TranslationsList( + heading="%(code)s: %(locale)s %(status)s", # type: ignore + # let children empty, it will be auto populated + ), + ObjectList( + heading=_("Régime"), + children=[FieldPanel("vegetarian"), FieldPanel("vegan")] + ), + ], + ) + """ class ParlerSnippetAdminMixin(ParlerAdminWagtailMixin, CompatibleSnippetViewSetMixin): + """ + Mixin to use with SnippetViewSet to manage parler translations. + + If no edit_handler are defined, the default behaviour will create an unstranlated data tab + then a tab for each language + You can specify your edit_handler to have more control over how form is built. + TranslationsList will be duplicated for each language and populated with + translations fields if no children are given. Of course, you can also configure + fields manually + ex: + + .. code-block:: python + + class SomeModelAdminSnippet(ParlerSnippetAdminMixin, SnippetViewSet): + model = SomeModel + + + class FoodAdminSnippet(ParlerSnippetAdminMixin, SnippetViewSet): + model = Food + edit_handler = ObjectList( + children=[ + FieldPanel("yum_rating"), + TranslationsList( + heading="%(code)s: %(locale)s %(status)s", + # let children empty, it will be auto populated + ), + ObjectList( + heading=_("Régime"), + children=[FieldPanel("vegetarian"), FieldPanel("vegan")] + ), + ], + ) + """ + def get_edit_handler(self: SnippetViewSet) -> TabbedInterface: return super().get_edit_handler().bind_to_model(self.model)