improve-doc

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:
+
+```

docs/source/index.md

@@ -1,8 +1,10 @@
 ```{include} presentation.md
 ```
+
 ```{toctree}
 :maxdepth: 2
 presentation
 configuration
 usage
+api
 ```

pyproject.toml

@@ -12,6 +12,7 @@
       | migrations
       | \.tox
       | \.venv
+      | docs/\.*/
     )/
     '''
 

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]

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 (

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)