feat(docs): Automatically generate format features docmentation#18106
feat(docs): Automatically generate format features docmentation#18106gersona wants to merge 19 commits intoWeblateOrg:mainfrom
Conversation
|
@nijel could you briefly have a look at the implementation suggestion before I move on to implement this for the other formats ? |
❌ 4 Tests Failed:
View the top 3 failed test(s) by shortest run time
To view more test analytics, go to the Test Analytics Dashboard |
nijel
left a comment
There was a problem hiding this comment.
Many of the features can already be detected from the file format class (monolingual, supports_explanation, supports_plural) so it might be better to define all such flags there without the need for the additional layer? I'm worried that with an additional layer, things will easily get out of sync.
The actual documentation generation then could live in the command.
|
That's a fair point, many flags can definitely be read directly from the format class. |
|
This pull request has been automatically marked as stale because there wasn’t any recent activity. It will be closed soon if no further action occurs. Thank you for your contributions! |
|
To make this easier to deal with, let's start with the features we already have flags for. Some are obvious, like |
|
I actually already got something quite ready for review, with a different approach than what I initially proposed.. |
c3cdbee to
7b4f024
Compare
|
I think this is a good direction. Can we get rid of existing SUPPORTS_FUZZY and use the new flags instead? |
|
one of the comments in #9077 mentions a doc page with an overview of features and the file formats that support them. Should it also be in the scope of this PR ? |
|
If all info from the “Translation types capabilities” is now covered directly in the formats doc, it should be removed. |
There was a problem hiding this comment.
Pull request overview
Adds an auto-generated “supported format features” documentation system by introducing a new list_format_features management command and wiring its output into the Sphinx docs (fixes #9077).
Changes:
- Added
list_format_featurescommand to generate per-format RST snippet tables of supported capabilities. - Extended format classes with explicit
supports_*capability flags andadditional_statesmetadata. - Updated documentation to include the generated snippets and adjusted docs build config/Makefile to generate/exclude snippet sources.
Reviewed changes
Copilot reviewed 110 out of 112 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| weblate/utils/management/base.py | Adds output_required to support commands that require an output destination. |
| weblate/formats/base.py | Introduces shared capability flags (supports_*) and additional_states on TranslationFormat. |
| weblate/formats/ttkit.py | Aligns fuzzy-state handling with additional_states and sets per-format capability flags. |
| weblate/formats/convert.py | Marks Windows RC format as supporting descriptions. |
| weblate/formats/management/commands/list_format_features.py | New generator command producing per-format “features” snippet files. |
| weblate/formats/tests/test_commands.py | Tests list_format_features basic argument validation and file generation. |
| docs/Makefile | Generates format-feature snippets during update-docs. |
| docs/conf.py | Excludes snippet files from being treated as standalone Sphinx documents. |
| docs/admin/management.rst | Documents the new list_format_features management command and its --output option. |
| docs/changes.rst | Adds changelog entries referencing the new command and doc improvements. |
| docs/formats.rst | Replaces a static capabilities table with guidance to refer to per-format pages. |
| docs/formats/android.rst | Includes generated format-features snippet on the Android format page. |
| docs/formats/apple.rst | Includes generated format-features snippet on the Apple Strings format page. |
| docs/formats/appstore.rst | Includes generated format-features snippet on the AppStore format page. |
| docs/formats/arb.rst | Includes generated format-features snippet on the ARB format page. |
| docs/formats/asciidoc.rst | Includes generated format-features snippet on the AsciiDoc format page. |
| docs/formats/catkeys.rst | Includes generated format-features snippet on the Catkeys format page. |
| docs/formats/compose-multiplatform-resources.rst | Includes generated format-features snippet for Compose Multiplatform resources. |
| docs/formats/csv.rst | Includes generated format-features snippet on the CSV format page. |
| docs/formats/dtd.rst | Includes generated format-features snippet on the DTD format page. |
| docs/formats/excel.rst | Includes generated format-features snippet on the Excel/XLSX format page. |
| docs/formats/flatxml.rst | Includes generated format-features snippet on the FlatXML format page. |
| docs/formats/fluent.rst | Includes generated format-features snippet on the Fluent format page. |
| docs/formats/formatjs.rst | Includes generated format-features snippet on the FormatJS format page. |
| docs/formats/gettext.rst | Includes generated format-features snippets for gettext (mono + bilingual). |
| docs/formats/go-i18n.rst | Includes generated format-features snippets for go-i18n variants. |
| docs/formats/gotext.rst | Includes generated format-features snippet on the GoText format page. |
| docs/formats/gwt.rst | Includes generated format-features snippet on the GWT format page. |
| docs/formats/html.rst | Includes generated format-features snippet on the HTML format page. |
| docs/formats/i18next.rst | Includes generated format-features snippets for i18next variants. |
| docs/formats/idml.rst | Includes generated format-features snippet on the IDML format page. |
| docs/formats/ini.rst | Includes generated format-features snippet on the INI format page. |
| docs/formats/innosetup.rst | Includes generated format-features snippet (ISLU) on the Inno Setup format page. |
| docs/formats/java.rst | Includes generated format-features snippet on the Java properties format page. |
| docs/formats/joomla.rst | Includes generated format-features snippet on the Joomla format page. |
| docs/formats/json.rst | Includes generated format-features snippet on the JSON format page. |
| docs/formats/laravel.rst | Includes generated format-features snippet on the Laravel format page. |
| docs/formats/markdown.rst | Includes generated format-features snippet on the Markdown format page. |
| docs/formats/mi18n.rst | Includes generated format-features snippet on the mi18n format page. |
| docs/formats/moko-resources.rst | Includes generated format-features snippet on the Moko resources format page. |
| docs/formats/nextcloud-json.rst | Includes generated format-features snippet on the Nextcloud JSON format page. |
| docs/formats/odf.rst | Includes generated format-features snippet on the ODF format page. |
| docs/formats/php.rst | Includes generated format-features snippet on the PHP format page. |
| docs/formats/qt.rst | Includes generated format-features snippet on the Qt/TS format page. |
| docs/formats/resjson.rst | Includes generated format-features snippet on the resjson format page. |
| docs/formats/resourcedict.rst | Includes generated format-features snippet on the resource dictionary format page. |
| docs/formats/resx.rst | Includes generated format-features snippet on the RESX format page. |
| docs/formats/ruby.rst | Includes generated format-features snippet on the Ruby YAML format page. |
| docs/formats/stringsdict.rst | Includes generated format-features snippet on the StringsDict format page. |
| docs/formats/subtitles.rst | Includes generated format-features snippet (SRT) on the subtitles format page. |
| docs/formats/tbx.rst | Replaces inline “features” content with an included snippet. |
| docs/formats/toml.rst | Includes generated format-features snippet on the TOML format page. |
| docs/formats/txt.rst | Includes generated format-features snippet on the TXT format page. |
| docs/formats/webextension.rst | Includes generated format-features snippet on the WebExtension format page. |
| docs/formats/winrc.rst | Includes generated format-features snippet on the Windows RC format page. |
| docs/formats/wxl.rst | Includes generated format-features snippet on the WXL format page. |
| docs/formats/xliff.rst | Includes generated format-features snippet on the XLIFF format page. |
| docs/formats/xliff2.rst | Includes generated format-features snippet on the XLIFF2 format page. |
| docs/formats/yaml.rst | Includes generated format-features snippet on the YAML format page. |
| docs/snippets/format-features/appstore-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/arb-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/aresource-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/asciidoc-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/catkeys-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/cmp-resource-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/csv-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/dtd-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/flatxml-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/fluent-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/formatjs-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/go-i18n-json-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/go-i18n-toml-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/gotext-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/gwt-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/html-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/i18next-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/i18nextv4-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/idml-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/ini-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/islu-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/joomla-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/json-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/laravel-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/markdown-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/mi18n-lang-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/moko-resource-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/nextcloud-json-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/odf-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/php-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/po-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/po-mono-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/properties-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/rc-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/resjson-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/resourcedictionary-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/resx-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/ruby-yaml-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/srt-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/strings-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/stringsdict-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/tbx-features.rst | New generated per-format snippet used by docs; retains some format-specific notes. |
| docs/snippets/format-features/toml-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/ts-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/txt-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/webextension-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/wxl-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/xliff-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/xliff2-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/xlsx-features.rst | New generated per-format snippet used by docs. |
| docs/snippets/format-features/yaml-features.rst | New generated per-format snippet used by docs. |
Comments suppressed due to low confidence (5)
weblate/formats/management/commands/list_format_features.py:1
common_extensionsis taken directly fromfile_format.get_class().Extensionsand then mutated with.append()/.extend(). IfExtensionsis a class-level list (or otherwise shared), this will leak extensions across formats and produce incorrect docs (e.g., unrelated extensions showing up for other formats). Fix by copying before mutation (e.g.,list(...)) and avoid mutating any class attribute returned by the toolkit.
weblate/utils/management/base.py:1- The help text always says "Optional output path", but
required=self.output_requiredmakes it mandatory for commands likelist_format_features. Consider making the help string conditional (required vs optional) so CLI help matches actual behavior.
weblate/formats/ttkit.py:1 supports_pluralsis introduced alongside the existingsupports_pluralflag and is inconsistent with the capability naming pattern used elsewhere in this PR (supports_plural,supports_descriptions, etc.). If this is meant to indicate plural support, it likely won’t be picked up by the generator (which readssupports_plural) and should be removed or renamed to the canonicalsupports_plural(or added to the shared base API if truly distinct).
weblate/formats/tests/test_commands.py:1- The test validates argument handling and that at least one output file exists, but it doesn’t assert any generated content. Adding a content assertion for a known format (e.g., that
php-features.rstcontains the expected markers and that its extension list doesn’t include unrelated extensions) would catch regressions like shared/mutated extension lists.
docs/snippets/format-features/tbx-features.rst:1 - These lines end with trailing commas, which is invalid/awkward RST punctuation and may render incorrectly. Remove the trailing commas (and consider converting these into a consistent list/table format) to keep the included snippet clean and Sphinx-friendly.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
029a8c9 to
8995259
Compare
|
The latest updates on your projects. Learn more about Argos notifications ↗︎
|
Uh oh!
There was an error while loading. Please reload this page.