Skip to content

Commit 3e8f720

Browse files
nijelnijel
authored
fix(docs): improve add-on snippets updating (#18661)
- do not rely on database state for the form help texts - hide hidden fields
1 parent 806697e commit 3e8f720

File tree

4 files changed

+71
-43
lines changed

4 files changed

+71
-43
lines changed

‎docs/snippets/addons-autogenerated.rst‎

Lines changed: 27 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -126,33 +126,33 @@ Automatic translation
126126
---------------------
127127

128128
:Add-on ID: ``weblate.autotranslate.autotranslate``
129-
:Configuration: +-----------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+
130-
| ``mode`` | Automatic translation mode | .. list-table:: Available choices: |
131-
| | | :width: 100% |
132-
| | | |
133-
| | | * - ``suggest`` |
134-
| | | - Add as suggestion |
135-
| | | * - ``translate`` |
136-
| | | - Add as translation |
137-
| | | * - ``fuzzy`` |
138-
| | | - Add as "Needing edit" |
139-
+-----------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+
140-
| ``q`` | Query | Please note that translating all strings will discard all existing translations. |
141-
+-----------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+
142-
| ``auto_source`` | Source of automated translations | .. list-table:: Available choices: |
143-
| | | :width: 100% |
144-
| | | |
145-
| | | * - ``others`` |
146-
| | | - Other translation components |
147-
| | | * - ``mt`` |
148-
| | | - Machine translation |
149-
+-----------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+
150-
| ``component`` | Component | Turn on contribution to shared translation memory for the project to get access to additional components. |
151-
+-----------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+
152-
| ``engines`` | Machine translation engines | :ref:`addon-choice-engines` |
153-
+-----------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+
154-
| ``threshold`` | Score threshold | |
155-
+-----------------+----------------------------------+-----------------------------------------------------------------------------------------------------------+
129+
:Configuration: +-----------------+----------------------------------+------------------------------------------------------------------------------------------------------+
130+
| ``mode`` | Automatic translation mode | .. list-table:: Available choices: |
131+
| | | :width: 100% |
132+
| | | |
133+
| | | * - ``suggest`` |
134+
| | | - Add as suggestion |
135+
| | | * - ``translate`` |
136+
| | | - Add as translation |
137+
| | | * - ``fuzzy`` |
138+
| | | - Add as "Needing edit" |
139+
+-----------------+----------------------------------+------------------------------------------------------------------------------------------------------+
140+
| ``q`` | Query | Please note that translating all strings will discard all existing translations. |
141+
+-----------------+----------------------------------+------------------------------------------------------------------------------------------------------+
142+
| ``auto_source`` | Source of automated translations | .. list-table:: Available choices: |
143+
| | | :width: 100% |
144+
| | | |
145+
| | | * - ``others`` |
146+
| | | - Other translation components |
147+
| | | * - ``mt`` |
148+
| | | - Machine translation |
149+
+-----------------+----------------------------------+------------------------------------------------------------------------------------------------------+
150+
| ``component`` | Component | Enter slug of a component to use as source, keep blank to use all components in the current project. |
151+
+-----------------+----------------------------------+------------------------------------------------------------------------------------------------------+
152+
| ``engines`` | Machine translation engines | :ref:`addon-choice-engines` |
153+
+-----------------+----------------------------------+------------------------------------------------------------------------------------------------------+
154+
| ``threshold`` | Score threshold | |
155+
+-----------------+----------------------------------+------------------------------------------------------------------------------------------------------+
156156

157157
:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-component-update`, :ref:`addon-event-daily`, :ref:`addon-event-event-change`
158158

@@ -331,8 +331,6 @@ Component discovery
331331
+---------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+
332332
| ``remove`` | Remove components for inexistent files | |
333333
+---------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+
334-
| ``confirm`` | I confirm the above matches look correct | |
335-
+---------------------------+-----------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+
336334

337335
:Triggers: :ref:`addon-event-add-on-installation`, :ref:`addon-event-repository-post-update`
338336

‎weblate/addons/management/commands/list_addons.py‎

Lines changed: 23 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -105,11 +105,20 @@ def generate_addons_doc(self) -> None:
105105
table: list[list[CellType]] = [
106106
[
107107
f"``{name}``",
108-
str(field.label),
109-
self.get_help_text(field, name),
108+
str(
109+
self.get_documented_field(
110+
obj.settings_form, name, field
111+
).label
112+
),
113+
self.get_help_text(
114+
self.get_documented_field(obj.settings_form, name, field),
115+
field,
116+
name,
117+
),
110118
]
111119
for name, field in form.fields.items()
112120
if (addon_name, name) not in SKIP_FIELDS
121+
and not field.widget.is_hidden
113122
]
114123

115124
for table_row in format_table(table, None):
@@ -123,6 +132,8 @@ def generate_addons_doc(self) -> None:
123132

124133
for name in self.params & set(form.fields):
125134
field = form.fields[name]
135+
if field.widget.is_hidden:
136+
continue
126137
choices = list(field.choices)
127138
if name == "engines":
128139
choices.extend(
@@ -164,10 +175,17 @@ def generate_addon_parameters_doc(self) -> None:
164175
["\n".join(items) for items in self.param_docs.values()],
165176
)
166177

167-
def get_help_text(self, field, name: str) -> str:
178+
def get_documented_field(self, form_class, name: str, field):
179+
return (
180+
form_class.base_fields.get(name)
181+
or form_class.declared_fields.get(name)
182+
or field
183+
)
184+
185+
def get_help_text(self, doc_field, field, name: str) -> str:
168186
result = []
169-
if field.help_text:
170-
result.append(format_rst_string(field.help_text))
187+
if doc_field.help_text:
188+
result.append(format_rst_string(doc_field.help_text))
171189
choices = getattr(field, "choices", None)
172190
if choices:
173191
if name in SHARED_PARAMS:

‎weblate/addons/tests.py‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1038,7 +1038,15 @@ class CommandTest(ViewTestCase):
10381038
def test_list_addons(self) -> None:
10391039
output = StringIO()
10401040
call_command("list_addons", stdout=output)
1041-
self.assertIn("msgmerge", output.getvalue())
1041+
generated = output.getvalue()
1042+
self.assertIn("msgmerge", generated)
1043+
self.assertIn(
1044+
"Enter slug of a component to use as source, keep blank to use all "
1045+
"components in the current project.",
1046+
generated,
1047+
)
1048+
# Hidden fields such as DiscoveryForm.confirm (HiddenInput) should not be documented
1049+
self.assertNotIn("confirm", generated)
10421050

10431051
def test_install_not_supported(self) -> None:
10441052
output = StringIO()

‎weblate/trans/forms.py‎

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -970,6 +970,15 @@ def clean(self):
970970
class AutoForm(forms.Form):
971971
"""Automatic translation form."""
972972

973+
COMPONENT_SLUG_HELP_TEXT = gettext_lazy(
974+
"Enter slug of a component to use as source, keep blank to use all "
975+
"components in the current project."
976+
)
977+
COMPONENT_SELECT_HELP_TEXT = gettext_lazy(
978+
"Turn on contribution to shared translation memory for the project to "
979+
"get access to additional components."
980+
)
981+
973982
mode = forms.ChoiceField(
974983
label=gettext_lazy("Automatic translation mode"),
975984
initial="suggest",
@@ -994,10 +1003,7 @@ class AutoForm(forms.Form):
9941003
component = forms.ChoiceField(
9951004
label=gettext_lazy("Component"),
9961005
required=False,
997-
help_text=gettext_lazy(
998-
"Turn on contribution to shared translation memory for the project to "
999-
"get access to additional components."
1000-
),
1006+
help_text=COMPONENT_SLUG_HELP_TEXT,
10011007
initial="",
10021008
)
10031009
engines = forms.MultipleChoiceField(
@@ -1047,10 +1053,7 @@ def __init__(
10471053
self.fields["component"] = forms.CharField(
10481054
required=False,
10491055
label=gettext("Component"),
1050-
help_text=gettext(
1051-
"Enter slug of a component to use as source, "
1052-
"keep blank to use all components in the current project."
1053-
),
1056+
help_text=self.fields["component"].help_text,
10541057
)
10551058
else:
10561059
choices = [
@@ -1062,6 +1065,7 @@ def __init__(
10621065
("", gettext("All components in current project")),
10631066
*choices,
10641067
]
1068+
self.fields["component"].help_text = self.COMPONENT_SELECT_HELP_TEXT
10651069

10661070
engines = sorted(
10671071
(

0 commit comments

Comments
 (0)