docs: update README (#40)

* docs: update README * ci: fix broken docs CI docs CI broke (probably due to upstream changes) so pinning it to a version * chore(build): auto-generate vimdoc * ci: simplify doc headings generated * chore(build): auto-generate vimdoc * chore: simplify main heading * chore(build): auto-generate vimdoc --------- Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
amitds1997 · Sep 1, 2023 · bd19550 · bd19550
1 parent da88176
commit bd19550
Show file tree

Hide file tree

Showing 3 changed files with 297 additions and 8 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -16,12 +16,13 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - name: panvimdoc
-        uses: kdheepak/panvimdoc@main
+        uses: kdheepak/panvimdoc@v3.0.6
         with:
-          vimdoc: remote-nvim.nvim
+          vimdoc: remote-nvim
           version: Neovim >= 0.8.0
           demojify: true
           treesitter: true
+          dedupsubheadings: false
       - name: Push changes
         uses: stefanzweifel/git-auto-commit-action@v4.16.0
         with:

diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# 🚀 Remote Nvim - Remote development in Neovim
+# 🚀 Remote Nvim
 
 **remote-nvim.nvim** brings the [Remote development using SSH](https://code.visualstudio.com/docs/remote/ssh)
 in VSCode to Neovim. If you use this plugin along with [devpod](https://github.com/loft-sh/devpod),
@@ -62,20 +62,21 @@ basically download locally and copy over the installation over SSH)
 ```lua
 {
    "amitds1997/remote-nvim.nvim",
-   tag = "v0.0.1", -- It is recommended that you keep this pinned to a tag
-   -- so that you do not pick up breaking changes
+   version = "*", -- This keeps it pinned to semantic releases
    dependencies = {
        "nvim-lua/plenary.nvim",
        "MunifTanjim/nui.nvim",
        "rcarriga/nvim-notify",
        -- This would be an optional dependency eventually
        "nvim-telescope/telescope.nvim",
-   }
+   },
+   config = true, -- This calls the default setup(); make sure to call it
 }
 ```
 
-After installation, run `:checkhealth remote-nvim` to verify that you have everything
-you need.
+After installation, run `:checkhealth remote-nvim` to verify that you have
+everything you need. This might fail if you have not initialized the plugin
+using `setup()` call.
 
 ## ⚙️ Configuration
 

diff --git a/doc/remote-nvim.txt b/doc/remote-nvim.txt
@@ -0,0 +1,287 @@
+*remote-nvim.txt*      For Neovim >= 0.8.0      Last change: 2023 September 01
+
+==============================================================================
+Table of Contents                              *remote-nvim-table-of-contents*
+
+1. Remote Nvim                                       |remote-nvim-remote-nvim|
+  - Demo                                                    |remote-nvim-demo|
+  - Requirements                                    |remote-nvim-requirements|
+  - Features                                            |remote-nvim-features|
+  - Installation                                    |remote-nvim-installation|
+  - Configuration                                  |remote-nvim-configuration|
+  - Usage                                                  |remote-nvim-usage|
+  - Caveats                                              |remote-nvim-caveats|
+  - Credits                                              |remote-nvim-credits|
+
+==============================================================================
+1. Remote Nvim                                       *remote-nvim-remote-nvim*
+
+**remote-nvim.nvim** brings the Remote development using SSH
+<https://code.visualstudio.com/docs/remote/ssh> in VSCode to Neovim. If you use
+this plugin along with devpod <https://github.com/loft-sh/devpod>, this also
+enables Dev Containers development natively from Neovim using this plugin.
+
+Plugin has been tested to work on Linux and MacOS. WSL and Windows support is
+planned (Author does not currently have access to Windows machine so
+contributions are welcome).
+
+**This plugin is still experimental. Breaking changes are expected (not a lot
+though).**
+
+
+DEMO                                                        *remote-nvim-demo*
+
+
+<http://www.youtube.com/watch?v=5qbDq1lGEx4%20%22Remote%20development%20on%20Neovim%20using%20remote-nvim.nvim%22>
+
+
+REQUIREMENTS                                        *remote-nvim-requirements*
+
+
+ON YOUR LOCAL MACHINE  ~
+
+1. AnOpenSSH client.
+2. Neovim >= 0.8.0
+3. Binaries: **curl**
+4. Following plugins:1. nui.nvim <https://github.com/MunifTanjim/nui.nvim> - For UI elements
+2. plenary.nvim <https://github.com/nvim-lua/plenary.nvim> - For standard
+functions
+3. nvim-notify <https://github.com/rcarriga/nvim-notify> - For progress notifications
+4. telescope.nvim <https://github.com/nvim-telescope/telescope.nvim> -
+For telescope extension (also the current default setup UI)
+
+
+
+
+ON YOUR REMOTE MACHINE  ~
+
+1. Arunning OpenSSH compliant server
+2. Access to internet (to download Neovim)
+3. Binaries: **curl** or **wget**; **tar** (if your remote machine is MacOS)
+4. **bash** must be present
+
+
+FEATURES                                                *remote-nvim-features*
+
+- Automatic installation of Neovim on remote
+- Automatic copying over your local Neovim configuration
+- Remember past sessions so that we can easily connect back to them
+- Control over how to launch your local client
+- Support for password-based SSH authentication
+- Automatic syncing of your local Neovim config on next run (or not, if you
+    so choose!)
+- Support to pick up hosts from your SSH configs
+- Support to clean up everything on your remote
+- Support for dev containers (using devpod <https://github.com/loft-sh/devpod>)
+- Remote development inside Docker container
+- Complete installation over SSH (without using internet on remote;
+    basically download locally and copy over the installation over SSH)
+
+
+INSTALLATION                                        *remote-nvim-installation*
+
+
+LAZY.NVIM ~
+
+>lua
+    {
+       "amitds1997/remote-nvim.nvim",
+       version = "", -- This keeps it pinned to semantic releases
+       dependencies = {
+           "nvim-lua/plenary.nvim",
+           "MunifTanjim/nui.nvim",
+           "rcarriga/nvim-notify",
+           -- This would be an optional dependency eventually
+           "nvim-telescope/telescope.nvim",
+       },
+       config = true, -- This calls the default setup(); make sure to call it
+    }
+<
+
+After installation, run `:checkhealth remote-nvim` to verify that you have
+everything you need. This might fail if you have not initialized the plugin
+using `setup()` call.
+
+
+CONFIGURATION                                      *remote-nvim-configuration*
+
+These are the default values. Alter them as needed for your personal use.
+
+>lua
+    {
+      -- Configuration for SSH connections made using this plugin
+      ssh_config = {
+      -- Binary with this name would be searched on your runtime path and would be
+      -- used to run SSH commands. Rename this if your SSH binary is something else
+        ssh_binary = "ssh",
+        -- Similar to `ssh_binary`, but for copying over files onto remote server
+        scp_binary = "scp",
+        -- All your SSH config file paths.
+        ssh_config_file_paths = { "$HOME/.ssh/config" },
+        -- This helps the plugin to understand when the underlying binary expects
+        -- input from user. This is useful for password-based authentication and
+        -- key-based authentication.
+        -- Explanation for each prompt:
+        -- match - string - This would be matched with the SSH output to decide if
+        -- SSH is waiting for input. This is a plain match (not a regex one)
+        -- type - string - Takes two values "secret" or "plain". "secret" indicates
+        -- that the value you would enter is a secret and should not be logged into
+        -- your input history
+        -- input_prompt - string - What is the input prompt that should be shown to
+        -- user when this match happens
+        -- value_type - string - Takes two values "static" and "dynamic". "static"
+        -- means that the value can be cached for the same prompt for future commands
+        -- (e.g. your password) so that you do not have to keep typing it again and
+        -- again. This is retained in-memory and is not logged anywhere. When you
+        -- close the editor, it is cleared from memory. "dynamic" is for something
+        -- like MFA codes which change every time.
+        ssh_prompts = {
+          {
+            match = "password:",
+            type = "secret",
+            input_prompt = "Enter password: ",
+            value_type = "static",
+            value = "",
+          },
+          {
+            match = "continue connecting (yes/no/[fingerprint])?",
+            type = "plain",
+            input_prompt = "Do you want to continue connection (yes/no)? ",
+            value_type = "static",
+            value = "",
+          },
+        },
+      },
+      -- Installation script location on local machine (If you have your own custom
+      -- installation script and you do not want to use the packaged install script.
+      -- It should accept the same inputs as the packaged install script though)
+      neovim_install_script_path = util.path_join(util.is_windows,
+      util.get_package_root(), "scripts", "neovim_install.sh"),
+      -- Where should everything that Remote Neovim does on remote be stored. By
+      -- default, it stores everything inside ~/.remote-nvim so as long as you
+      -- delete that folder, you essentially wipe out everything that remote-nvim
+      -- has over there.
+      remote_neovim_install_home = util.path_join(util.is_windows, "~", ".remote-nvim"),
+      -- Where is your personal Neovim config stored?
+      neovim_user_config_path = vim.fn.stdpath("config"),
+      local_client_config = {
+        -- modify this function to override how your client launches
+        -- function should accept two arguments function(local_port, workspace_config)
+        -- local_port is the port on which the remote server is available locally
+        -- workspace_config contains the workspace config. For all attributes present
+        -- in it, see WorkspaceConfig in ./lua/remote-nvim/config.lua.
+        -- See examples of callback in https://github.com/amitds1997/remote-nvim.nvim/wiki/Configuration-recipes
+        callback = nil,
+        -- [Subject to change]: These values may be subject to change, so there
+        -- might be a breaking change. Right now, it uses the [plenary.nvimwin_float.percentage_range_window](https://github.com/nvim-lua/plenary.nvim/blob/267282a9ce242bbb0c5dc31445b6d353bed978bb/lua/plenary/window/float.luaL138C25-L138C25)
+        default_client_config = {
+          col_percent = 0.9,
+          row_percent = 0.9,
+          win_opts = {
+            winblend = 0,
+          },
+          border_opts = {
+            topleft = "",
+            topright = "",
+            top = "",
+            left = "",
+            right = "",
+            botleft = "",
+            botright = "",
+            bot = "",
+          },
+        },
+      },
+
+    }
+<
+
+
+USAGE                                                      *remote-nvim-usage*
+
+Following user commands are available.
+
+
+REMOTESTART ~
+
+Used to setup/start session on a remote host. It can optionally take an input
+as one of your earlier saved host configuration to make start faster. If ran
+without an option, it launched a Telescope extension that guides you towards
+creating a remote session.
+
+
+REMOTESTOP ~
+
+The plugin allows you to stop the remote server that was launched on a host.
+Takes an argument from any of the running sessions.
+
+
+REMOTELOG ~
+
+See the plugin log file to see what the plugin is doing. It does not log much,
+until you drop to the debug level. To start logging in debug level, start your
+Neovim instance as `REMOTE_NVIM_LOG_LEVEL="debug" nvim`
+
+
+REMOTESESSIONINFO ~
+
+Provides you a view of all your currently running sessions. In case, you
+decided not to start a client, the connection string that can be used to
+connect to any of the running remote servers also shows up on this info box.
+
+
+REMOTECLEANUP ~
+
+If you decide that you want to clean up remote neovim from a host or are in a
+situation where you need to start afresh, you can use this command. It takes as
+an argument input the remote host that you want to cleanup. Once you cleanup,
+it deletes the local saved configuration for the host, so next time, you can
+start afresh.
+
+
+REMOTECONFIGDEL ~
+
+Sometimes, you are working on a remote instance and that remote instance is no
+longer there. And you have this one config just left in there that keeps
+nagging you. This takes any number of arguments where each argument is a saved
+workspace configuration that you want to delete from your local. Think of this
+as your Remote Neovim sweeping broom.
+
+
+CAVEATS                                                  *remote-nvim-caveats*
+
+- Just because how Neovim server and client currently work, it is not possible
+    to deterministically close a TUI so in case you do a `:q`, the server and the
+    client both die. You can read the discussion here <https://github.com/neovim/neovim/issues/23093>
+    to figure out your own way forward to just close a TUI or else just relaunch the
+    session using `:RemoteStart`. It should be fast, after setup, if you are on a
+    good network.
+- When we launch the remote server, it is associated with the Neovim instance it
+    is launched from. Closing that Neovim instance would close the server as well.
+- This plugin does not introduce any changes in your PATH variables on remote
+    server. Instead it runs with by modifying the `XDG_` variables when launching
+    your remote Neovim instance so that your entire data is contained inside your
+    remote neovim folder. So, take care when using any operations that depend on it.
+- Sometimes, our Neovim configurations are buggy and when your client launches,
+    you would see a fresh, clean Neovim installation (assuming you copied your
+    Neovim config over). This is no fault with the plugin. Run `:messages` to see
+    what went wrong. Usually, `git` or some other important binary is not available
+    on the remote in some docker systems.
+
+
+CREDITS                                                  *remote-nvim-credits*
+
+I have learnt a lot from all the different plugins; and want to extend a thank
+you to all the plugin authors. You all are awesome
+
+Thepackage structure, CIs have been borrowed with some modifications from the
+lazy.nvim <https://github.com/folke/lazy.nvim/> plugin.
+
+==============================================================================
+2. Links                                                   *remote-nvim-links*
+
+1. *Tutorialfor remote-nvim.nvim plugin v0.0.1*: http://img.youtube.com/vi/5qbDq1lGEx4/0.jpg
+
+Generated by panvimdoc <https://github.com/kdheepak/panvimdoc>
+
+vim:tw=78:ts=8:noet:ft=help:norl: