feat: add toggle_doc functionality (#1647)

* feat: Add toggle_doc functionality

fix: Update docs view on entry change

* Replace toggle logic by open/close

* add docs and pinned flags

* add faq for disabling docs

* chore(git): ignore .DS_Store

---------

Co-authored-by: hrsh7th <629908+hrsh7th@users.noreply.github.com>

doc/cmp.txt

@@ -155,6 +155,9 @@ NOTE: `<Cmd>lua require('cmp').complete()<CR>` can be used to call these functio
 *cmp.visible* ()
   Return a boolean showing whether the completion menu is visible or not.
 
+*cmp.visible_docs* ()
+  Return a boolean showing whether the docs window is visible or not.
+
 *cmp.get_entries* ()
   Return all current entries.
 
@@ -197,6 +200,11 @@ NOTE: `<Cmd>lua require('cmp').complete()<CR>` can be used to call these functio
     }
   }
 <
+*cmp.open_docs* ()
+  Open docs view.
+
+*cmp.close_docs* ()
+  Close docs view.
 
 *cmp.scroll_docs* (delta: number)
   Scroll the documentation window if visible.
@@ -335,6 +343,12 @@ There are also builtin mapping helper functions you can use:
   *cmp.mapping.select_prev_item* (option: { behavior = cmp.SelectBehavior, count = 1 })
     Same as |cmp.select_prev_item|.
 
+  *cmp.mapping.open_docs* ()
+    Same as |cmp.open_docs|.
+
+  *cmp.mapping.close_docs* ()
+    Same as |cmp.close_docs|.
+
   *cmp.mapping.scroll_docs* (delta: number)
     Same as |cmp.scroll_docs|.
 
@@ -659,6 +673,12 @@ view~
   The view class used to customize nvim-cmp's appearance.
   Currently available configuration options are:
 
+                                                *cmp-config.view.docs.auto_open*
+view.docs.auto_open~
+  `boolean`
+
+  Specify whether to show the docs_view when selecting an item.
+
                            *cmp-config.window.{completion,documentation}.border*
 window.{completion,documentation}.border~
   `string | string[] | nil`
@@ -900,6 +920,38 @@ How to disable commitCharacters?~
   }
 <
 
+How to disable automatic display of docs view?~
+
+  You can add the `view.docs.auto_open = false` for configuration.
+>lua
+  cmp.setup {
+    ...
+    view = {
+      docs = {
+        auto_open = false
+      }
+    }
+    ...
+  }
+<
+
+  additionaly, if you want to open/close docs view via your key mapping, you
+  can define keymapping as the following.
+>lua
+  cmp.setup {
+    ...
+    mapping = {
+      ['<C-g>'] = function()
+        if cmp.visible_docs() then
+          cmp.close_docs()
+        else
+          cmp.open_docs()
+        end
+      end
+    }
+    ...
+  }
+<
 
 How to disable auto-completion?~
 How to use nvim-cmp as omnifunc?~