Git commit 972c60c1fcc4996c54dfba5ee767043d3c7e7b20 by Waqar Ahmed. Committed on 13/05/2024 at 17:17. Pushed by waqar into branch 'master'.
Document formatting plugin M +146 -0 doc/kate/plugins.docbook https://invent.kde.org/utilities/kate/-/commit/972c60c1fcc4996c54dfba5ee767043d3c7e7b20 diff --git a/doc/kate/plugins.docbook b/doc/kate/plugins.docbook index a3a1ed4a0e..7d6b16abaf 100644 --- a/doc/kate/plugins.docbook +++ b/doc/kate/plugins.docbook @@ -123,6 +123,9 @@ attributes, attribute values and entities allowed by DTD</para> <listitem> <para><link linkend="kate-application-plugin-compilerexplorer">Compiler Explorer</link>- Interface to compiler explorer tool</para> </listitem> +<listitem> +<para><link linkend="kate-application-plugin-formatting">Formatting</link>- Code formatting plugin</para> +</listitem> </itemizedlist> </sect1> @@ -4407,4 +4410,147 @@ The first thing you need to do is to open a compiler explorer tab. Hit <keycombo </sect1> +<!-- BEGIN Format plugin --> + +<sect1 id="kate-application-plugin-formatting"> +<title>Formatting Plugin</title> + +<para>The formatting plugin allows one to format code easily. The plugin aims to preserve the +document's undo history and user's cursor position when formatting the code so that the formatting +of code doesn't disrupt user's work. This is especially important for automatic formatting on save.</para> + +<sect2 id="formatting-how-to-use"> +<title>Usage</title> + +<para> +It allows the user to format code in two ways: +<itemizedlist> +<listitem><para>Manually using the "Format Document" action.</para></listitem> +<listitem><para>Automatically on save</para></listitem> +</itemizedlist> +</para> + +<tip><para>You can search for this action in the command bar and bind a shortcut to it for easier access</para></tip> + +</sect2> + +<sect2 id="formatting-supported-langs-formatters"> +<title>Supported languages and formatters</title> + +<para> +The current list of supported languages and formatters are as follows: +<itemizedlist> + +<listitem><para>C/C++/ObjectiveC/ObjectiveC++/Protobuf - <command>clang-format</command> +</para></listitem> + +<listitem><para>Javascript/Typescript/JSX/TSX - <command>prettier</command> +</para></listitem> + +<listitem><para>JSON +<itemizedlist> + <listitem><para><command>prettier</command></para></listitem> + <listitem><para><command>clang-format</command></para></listitem> + <listitem><para><command>jq</command></para></listitem> +</itemizedlist> +</para></listitem> + +<listitem><para>Dart - <command>dartfmt</command> +</para></listitem> +<listitem><para>Rust - <command>rustfmt</command> +</para></listitem> +<listitem><para>Go - <command>gofmt</command> +</para></listitem> +<listitem><para>XML - <command>xmllint</command> +</para></listitem> +<listitem><para>Zig - <command>zigfmt</command> +</para></listitem> +<listitem><para>CMake - <command>cmake-format</command> +</para></listitem> + +<listitem><para>Python +<itemizedlist> + <listitem><para><command>autopep8</command></para></listitem> + <listitem><para><command>ruff</command></para></listitem> +</itemizedlist> +</para></listitem> + +</itemizedlist> +</para> + +</sect2> + +<sect2 id="formatting-plugin-configuring"> +<title>Configuring</title> + +<para>The plugin can be configured in two ways: +<itemizedlist> +<listitem><para>Globally, from the Configure dialog</para></listitem> +<listitem><para>On a per project basis using the <filename>.kateproject</filename> file</para></listitem> +</itemizedlist> +</para> + +<para>When reading the config, the plugin will first try to read the config from <filename>.kateproject</filename> file and then read the global config. +Example: +</para> + +<screen> +{ + "formatOnSave": true, + "formatterForJson": "jq", + "cmake-format": { + "formatOnSave": false + }, + "autopep8": { + "formatOnSave": false + } +} +</screen> + +<para>The above: +<itemizedlist> +<listitem><para>enables "format on save" globally</para></listitem> +<listitem><para>specifies "jq" as the formatter for JSON</para></listitem> +<listitem><para>disables "format on save" for cmake-format and autopep8</para></listitem> +</itemizedlist> +</para> + +<para>To configure formatting for a project, first create a <filename>.kateproject</filename> file and then add a <code>"formatting"</code> object to it. +In the <code>"formatting"</code> object you can specify your settings as shown in the previous example. Example: +</para> +<note><para>You need to enable the <link linkend="kate-application-plugin-projects">Project plugin</link> for this to work</para></note> + +<screen> +{ + "name": "My Cool Project", + "files": [ + { + "git": 1 + } + ], + "formatting": { + "formatterForJson": "clang-format", + "autopep8": { + "formatOnSave": false + } + } +} +</screen> + +</sect2> + +<sect2 id="formatting-plugin-temp-disable-autosave-format"> +<title>Temporarily disable format on save</title> + +<para> +While working you will often need to disable the formatting for a short while due to any reason. +You can do this from the menubar, <menuchoice><guimenu>Tools</guimenu> <guimenuitem>Format on Save</guimenuitem></menuchoice>. You can also trigger this action from the <guilabel>Command bar</guilabel>. +</para> + +</sect2> + +</sect1> + +<!-- END Format plugin --> + </chapter>
