yarn: adjust docs (#9279)

plugins/modules/yarn.py

@@ -11,12 +11,11 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
 
-DOCUMENTATION = '''
+DOCUMENTATION = r"""
----
 module: yarn
-short_description: Manage node.js packages with Yarn
+short_description: Manage Node.js packages with Yarn
 description:
-  - Manage node.js packages with the Yarn package manager (https://yarnpkg.com/)
+  - Manage Node.js packages with the Yarn package manager U(https://yarnpkg.com/).
 author:
   - "David Gunter (@verkaufer)"
   - "Chris Hoffman (@chrishoffman), creator of NPM Ansible module)"
@@ -31,25 +30,25 @@ options:
   name:
     type: str
     description:
-      - The name of a node.js library to install
+      - The name of a Node.js library to install.
       - If omitted all packages in package.json are installed.
-      - To globally install from local node.js library. Prepend "file:" to the path of the node.js library.
+      - To globally install from local Node.js library. Prepend C(file:) to the path of the Node.js library.
     required: false
   path:
     type: path
     description:
       - The base path where Node.js libraries will be installed.
-      - This is where the node_modules folder lives.
+      - This is where the C(node_modules) folder lives.
     required: false
   version:
     type: str
     description:
       - The version of the library to be installed.
-      - Must be in semver format. If "latest" is desired, use "state" arg instead
+      - Must be in semver format. If "latest" is desired, use O(state) arg instead.
     required: false
   global:
     description:
-      - Install the node.js library globally
+      - Install the Node.js library globally.
     required: false
     default: false
     type: bool
@@ -60,14 +59,14 @@ options:
     required: false
   ignore_scripts:
     description:
-      - Use the --ignore-scripts flag when installing.
+      - Use the C(--ignore-scripts) flag when installing.
     required: false
     type: bool
     default: false
   production:
     description:
       - Install dependencies in production mode.
-      - Yarn will ignore any dependencies under devDependencies in package.json
+      - Yarn will ignore any dependencies under devDependencies in C(package.json).
     required: false
     type: bool
     default: false
@@ -79,88 +78,61 @@ options:
   state:
     type: str
     description:
-      - Installation state of the named node.js library
+      - Installation state of the named Node.js library.
-      - If absent is selected, a name option must be provided
+      - If V(absent) is selected, a O(name) option must be provided.
     required: false
     default: present
-    choices: [ "present", "absent", "latest" ]
+    choices: ["present", "absent", "latest"]
 requirements:
-    - Yarn installed in bin path (typically /usr/local/bin)
+  - Yarn installed in bin path (typically C(/usr/local/bin))
-'''
+"""
 
-EXAMPLES = '''
+EXAMPLES = r"""
-- name: Install "imagemin" node.js package.
+  - name: Install "imagemin" Node.js package.
-  community.general.yarn:
+    community.general.yarn:
-    name: imagemin
+      name: imagemin
-    path: /app/location
+      path: /app/location
 
-- name: Install "imagemin" node.js package on version 5.3.1
+  - name: Install "imagemin" Node.js package on version 5.3.1
-  community.general.yarn:
+    community.general.yarn:
-    name: imagemin
+      name: imagemin
-    version: '5.3.1'
+      version: '5.3.1'
-    path: /app/location
+      path: /app/location
 
-- name: Install "imagemin" node.js package globally.
+  - name: Install "imagemin" Node.js package globally.
-  community.general.yarn:
+    community.general.yarn:
-    name: imagemin
+      name: imagemin
-    global: true
+      global: true
 
-- name: Remove the globally-installed package "imagemin".
+  - name: Remove the globally-installed package "imagemin".
-  community.general.yarn:
+    community.general.yarn:
-    name: imagemin
+      name: imagemin
-    global: true
+      global: true
-    state: absent
+      state: absent
 
-- name: Install "imagemin" node.js package from custom registry.
+  - name: Install "imagemin" Node.js package from custom registry.
-  community.general.yarn:
+    community.general.yarn:
-    name: imagemin
+      name: imagemin
-    registry: 'http://registry.mysite.com'
+      registry: 'http://registry.mysite.com'
 
-- name: Install packages based on package.json.
+  - name: Install packages based on package.json.
-  community.general.yarn:
+    community.general.yarn:
-    path: /app/location
+      path: /app/location
 
-- name: Update all packages in package.json to their latest version.
+  - name: Update all packages in package.json to their latest version.
-  community.general.yarn:
+    community.general.yarn:
-    path: /app/location
+      path: /app/location
-    state: latest
+      state: latest
-'''
+"""
 
-RETURN = '''
+RETURN = r"""
-changed:
-    description: Whether Yarn changed any package data
-    returned: always
-    type: bool
-    sample: true
-msg:
-    description: Provides an error message if Yarn syntax was incorrect
-    returned: failure
-    type: str
-    sample: "Package must be explicitly named when uninstalling."
-invocation:
-    description: Parameters and values used during execution
-    returned: success
-    type: dict
-    sample: {
-            "module_args": {
-                "executable": null,
-                "globally": false,
-                "ignore_scripts": false,
-                "name": null,
-                "path": "/some/path/folder",
-                "production": false,
-                "registry": null,
-                "state": "present",
-                "version": null
-            }
-        }
 out:
-    description: Output generated from Yarn.
+  description: Output generated from Yarn.
-    returned: always
+  returned: always
-    type: str
+  type: str
-    sample: "yarn add v0.16.1[1/4] Resolving packages...[2/4] Fetching packages...[3/4] Linking dependencies...[4/4]
+  sample: "yarn add v0.16.1[1/4] Resolving packages...[2/4] Fetching packages...[3/4] Linking dependencies...[4/4] Building fresh packages...success
-    Building fresh packages...success Saved lockfile.success Saved 1 new dependency..left-pad@1.1.3 Done in 0.59s."
+    Saved lockfile.success Saved 1 new dependency..left-pad@1.1.3 Done in 0.59s."
-'''
+"""
 
 import os
 import json