docs: Improve Ansible docs (#49682)

Liffindra Angga Zaaldian and Kunall Banerjee created 1 month ago

Small fixes to documentation:

- split paragraph for better readability and context understanding.
- add curly braces for settings example for consistency
- capitalize abbreviation (YAML, JSON)
- change note style for consistency

Release Notes:

- N/A

---------

Co-authored-by: Kunall Banerjee <[e-mail]>

Change summary

docs/src/languages/ansible.md | 68 ++++++++++++++++++++----------------
1 file changed, 37 insertions(+), 31 deletions(-)

Detailed changes

docs/src/languages/ansible.md

@@ -14,10 +14,13 @@ Support for Ansible in Zed is provided via a community-maintained [Ansible exten
 
 ### File detection
 
-To avoid mishandling non-Ansible YAML files, the Ansible Language is not associated with any file extensions by default. To change this behavior you can add a `"file_types"` section to Zed settings inside your project (`.zed/settings.json`) or your Zed user settings (`~/.config/zed/settings.json`) to match your folder/naming conventions. For example:
+To avoid mishandling non-Ansible YAML files, the Ansible Language is not associated with any file extensions by default.
+
+To change this behavior, you can add a `"file_types"` section to Zed settings inside your project (`.zed/settings.json`) or your Zed user settings (`~/.config/zed/settings.json`) to match your folder/naming conventions. For example:
 
 ```json [settings]
-"file_types": {
+{
+  "file_types": {
     "Ansible": [
       "**.ansible.yml",
       "**.ansible.yaml",
@@ -39,6 +42,7 @@ To avoid mishandling non-Ansible YAML files, the Ansible Language is not associa
       "**playbook*.yaml"
     ]
   }
+}
 ```
 
 Feel free to modify this list as per your needs.
@@ -47,34 +51,36 @@ Feel free to modify this list as per your needs.
 
 If your inventory file is in the YAML format, you can either:
 
-- Append the `ansible-lint` inventory json schema to it via the following comment at the top of your inventory file:
+- Append the `ansible-lint` inventory JSON schema to it via the following comment at the top of your inventory file:
 
 ```yml
 # yaml-language-server: $schema=https://raw.githubusercontent.com/ansible/ansible-lint/main/src/ansiblelint/schemas/inventory.json
 ```
 
-- Or configure the yaml language server settings to set this schema for all your inventory files, that match your inventory pattern, under your Zed settings ([ref](https://zed.dev/docs/languages/yaml)):
+- or, configure the YAML language server settings to set this schema for all your inventory files, that match your inventory pattern, under your Zed settings ([ref](https://zed.dev/docs/languages/yaml)):
 
 ```json [settings]
-"lsp": {
+{
+  "lsp": {
     "yaml-language-server": {
       "settings": {
         "yaml": {
           "schemas": {
             "https://raw.githubusercontent.com/ansible/ansible-lint/main/src/ansiblelint/schemas/inventory.json": [
               "./inventory/*.yaml",
-              "hosts.yml",
+              "hosts.yml"
             ]
           }
         }
       }
     }
-},
+  }
+}
 ```
 
 ### LSP Configuration
 
-By default, the following default config is passed to the Ansible language server. It conveniently mirrors the defaults set by [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig/blob/03bc581e05e81d33808b42b2d7e76d70adb3b595/lua/lspconfig/configs/ansiblels.lua) for the Ansible language server:
+By default, the following configuration is passed to the Ansible language server. It conveniently mirrors the defaults set by [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig/blob/03bc581e05e81d33808b42b2d7e76d70adb3b595/lua/lspconfig/configs/ansiblels.lua) for the Ansible language server:
 
 ```json
 {
@@ -99,31 +105,32 @@ By default, the following default config is passed to the Ansible language serve
 }
 ```
 
-> [!NOTE]
-> In order for linting to work, ensure that `ansible-lint` is installed and discoverable on your PATH
+> **Note:** In order for linting to work, ensure that `ansible-lint` is installed and discoverable on your `$PATH`.
 
 When desired, any of the above default settings can be overridden under the `"lsp"` section of your Zed settings file. For example:
 
 ```json [settings]
-"lsp": {
-  // Note, the Zed Ansible extension prefixes all settings with `ansible`
-  // so instead of using `ansible.ansible.path` use `ansible.path`.
-  "ansible-language-server": {
-    "settings": {
-      "ansible": {
-        "path": "ansible"
-      },
-      "executionEnvironment": {
-        "enabled": false
-      },
-      "python": {
-        "interpreterPath": "python3"
-      },
-      "validation": {
-        "enabled": false, // disable validation
-        "lint": {
-          "enabled": false, // disable ansible-lint
-          "path": "ansible-lint"
+{
+  "lsp": {
+    // The Zed Ansible extension prefixes all settings with `ansible`
+    // so use `ansible.path` instead of `ansible.ansible.path`.
+    "ansible-language-server": {
+      "settings": {
+        "ansible": {
+          "path": "ansible"
+        },
+        "executionEnvironment": {
+          "enabled": false
+        },
+        "python": {
+          "interpreterPath": "python3"
+        },
+        "validation": {
+          "enabled": false,
+          "lint": {
+            "enabled": false,
+            "path": "ansible-lint"
+          }
         }
       }
     }
@@ -131,5 +138,4 @@ When desired, any of the above default settings can be overridden under the `"ls
 }
 ```
 
-A full list of options/settings, that can be passed to the server, can be found at the project's page [here](https://github.com/ansible/vscode-ansible/blob/5a89836d66d470fb9d20e7ea8aa2af96f12f61fb/docs/als/settings.md).
-Feel free to modify option values as needed.
+A full list of options/settings that can be passed to the server can be found at the project's page [here](https://github.com/ansible/vscode-ansible/blob/main/docs/als/settings.md).