docs: centralize documentation into helpdoc

Problem: documentation was spread across four files (README.md,
doc/oil.txt, doc/api.md, doc/recipes.md) with duplication and gaps.
User events were undocumented, and adapter docs only lived in the
README.

Solution: expand doc/oil.txt with five new sections (introduction,
requirements, adapters, recipes, events) from existing content. Trim
README to a landing page pointing to :help oil. Delete doc/api.md
and doc/recipes.md since their content now lives in the helpdoc.

Closes: barrettruth/oil.nvim#6

.envrc

@@ -1 +1,3 @@
-use flake
+export VIRTUAL_ENV=venv
+layout python
+python -c 'import pyparsing' 2>/dev/null || pip install -r scripts/requirements.txt

.github/workflows/automation_request_review.yml

@@ -4,6 +4,8 @@ permissions:
 on:
   pull_request_target:
     types: [opened, reopened, ready_for_review, synchronize]
+    branches-ignore:
+      - "release-please--**"
 
 jobs:
   # Request review automatically when PRs are opened

.github/workflows/luarocks.yaml

@@ -1,21 +0,0 @@
-name: luarocks
-
-on:
-  push:
-    tags:
-      - 'v*'
-
-jobs:
-  quality:
-    uses: ./.github/workflows/tests.yml
-
-  publish:
-    needs: quality
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: nvim-neorocks/luarocks-tag-release@v7
-        env:
-          LUAROCKS_API_KEY: ${{ secrets.LUAROCKS_API_KEY }}

.github/workflows/tests.yml

@@ -1,7 +1,6 @@
 name: Tests
 
 on:
-  workflow_call:
   push:
     branches:
       - main
@@ -10,14 +9,21 @@ on:
       - main
 
 jobs:
-  selene:
+  luacheck:
-    name: Selene
+    name: Luacheck
     runs-on: ubuntu-22.04
     steps:
       - uses: actions/checkout@v4
-      - uses: NTBBloodbath/selene-action@v1.0.0
+
-        with:
+      - name: Prepare
-          args: --display-style quiet .
+        run: |
+          sudo apt-get update
+          sudo add-apt-repository universe
+          sudo apt install luarocks -y
+          sudo luarocks install luacheck
+
+      - name: Run Luacheck
+        run: luacheck lua tests
 
   stylua:
     name: StyLua
@@ -63,3 +69,46 @@ jobs:
       - name: Run tests
         run: |
           bash ./run_tests.sh
+
+  update_docs:
+    name: Update docs
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Neovim and dependencies
+        run: |
+          bash ./.github/workflows/install_nvim.sh
+
+      - name: Update docs
+        run: |
+          python -m pip install pyparsing==3.0.9
+          make doc
+      - name: Check docs are up to date
+        run: |
+          git diff --exit-code README.md doc
+
+  release:
+    name: release
+
+    if: ${{ github.ref == 'refs/heads/main' }}
+    needs:
+      - luacheck
+      - stylua
+      - typecheck
+      - run_tests
+      - update_docs
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: googleapis/release-please-action@v4
+        id: release
+        with:
+          release-type: simple
+      - uses: actions/checkout@v4
+      - uses: rickstaa/action-create-tag@v1
+        if: ${{ steps.release.outputs.release_created }}
+        with:
+          tag: stable
+          message: "Current stable release: ${{ steps.release.outputs.tag_name }}"
+          tag_exists_error: false
+          force_push_tag: true

.gitignore

@@ -6,6 +6,9 @@ luac.out
 *.zip
 *.tar.gz
 
+# python bytecode
+__pycache__
+
 # Object files
 *.o
 *.os
@@ -41,7 +44,9 @@ luac.out
 
 .direnv/
 .testenv/
+venv/
 doc/tags
+scripts/nvim_doc_tools
 scripts/nvim-typecheck-action
 scripts/benchmark.nvim
 perf/tmp/

.luacheckrc

@@ -0,0 +1,19 @@
+max_comment_line_length = false
+codes = true
+
+exclude_files = {
+  "tests/treesitter",
+}
+
+ignore = {
+  "212", -- Unused argument
+  "631", -- Line is too long
+  "122", -- Setting a readonly global
+  "542", -- Empty if branch
+}
+
+read_globals = {
+  "vim",
+  "a",
+  "assert",
+}

.pre-commit-config.yaml

@@ -1,17 +0,0 @@
-minimum_pre_commit_version: '3.5.0'
-
-repos:
-  - repo: https://github.com/JohnnyMorganz/StyLua
-    rev: v2.3.1
-    hooks:
-      - id: stylua-github
-        name: stylua (Lua formatter)
-        files: \.lua$
-        pass_filenames: true
-
-  - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v4.0.0-alpha.8
-    hooks:
-      - id: prettier
-        name: prettier
-        files: \.(md|toml|yaml|yml|sh)$

Makefile

@@ -4,9 +4,19 @@ help:
 	@echo 'Usage:'
 	@sed -n 's/^##//p' ${MAKEFILE_LIST} | column -t -s ':' |  sed -e 's/^/ /'
 
-## all: lint and run tests
+## all: generate docs, lint, and run tests
 .PHONY: all
-all: lint test
+all: doc lint test
+
+venv:
+	python3 -m venv venv
+	venv/bin/pip install -r scripts/requirements.txt
+
+## doc: generate documentation
+.PHONY: doc
+doc: scripts/nvim_doc_tools venv
+	venv/bin/python scripts/main.py generate
+	venv/bin/python scripts/main.py lint
 
 ## test: run tests
 .PHONY: test
@@ -15,9 +25,14 @@ test:
 
 ## lint: run linters and LuaLS typechecking
 .PHONY: lint
-lint: scripts/nvim-typecheck-action
+lint: scripts/nvim-typecheck-action fastlint
 	./scripts/nvim-typecheck-action/typecheck.sh --workdir scripts/nvim-typecheck-action lua
-	selene --display-style quiet .
+
+## fastlint: run only fast linters
+.PHONY: fastlint
+fastlint: scripts/nvim_doc_tools venv
+	venv/bin/python scripts/main.py lint
+	luacheck lua tests --formatter plain
 	stylua --check lua tests
 
 ## profile: use LuaJIT profiler to profile the plugin
@@ -36,6 +51,9 @@ benchmark: scripts/benchmark.nvim
 	nvim --clean -u perf/bootstrap.lua -c 'lua benchmark()'
 	@cat perf/tmp/benchmark.txt
 
+scripts/nvim_doc_tools:
+	git clone https://github.com/stevearc/nvim_doc_tools scripts/nvim_doc_tools
+
 scripts/nvim-typecheck-action:
 	git clone https://github.com/stevearc/nvim-typecheck-action scripts/nvim-typecheck-action
 
@@ -45,4 +63,4 @@ scripts/benchmark.nvim:
 ## clean: reset the repository to a clean state
 .PHONY: clean
 clean:
-	rm -rf scripts/nvim-typecheck-action .testenv perf/tmp profile.json
+	rm -rf scripts/nvim_doc_tools scripts/nvim-typecheck-action venv .testenv perf/tmp profile.json

README.md

@@ -66,50 +66,33 @@ Neovim 0.8+ and optionally [mini.icons](https://github.com/nvim-mini/mini.nvim/b
 
 ## Installation
 
-Install with your favorite package manager or with luarocks:
+Install with your favorite package manager or with luarocks.
 
-```console
+## Quick start
-luarocks install oil.nvim
+
+Add the following to your init.lua
+
+```lua
+require("oil").setup()
 ```
 
+Then open a directory with `nvim .`. Use `<CR>` to open a file/directory, and `-` to go up a directory. Otherwise, just treat it like a normal buffer and make changes as you like. Remember to `:w` when you're done to actually perform the actions.
+
+If you want to mimic the `vim-vinegar` method of navigating to the parent directory of a file, add this keymap:
+
+```lua
+vim.keymap.set("n", "-", "<CMD>Oil<CR>", { desc = "Open parent directory" })
+```
+
+You can open a directory with `:edit <path>` or `:Oil <path>`. To open oil in a floating window, do `:Oil --float <path>`.
+
 ## Documentation
 
-```vim
+See `:help oil` for configuration, API reference, recipes, and more.
-:help oil.nvim
-```
 
 ## FAQ
 
-**Q: How do I migrate from `stevearc/oil.nvim` to `barrettruth/oil.nvim`?**
+**Q: Why "oil"**?
-
-Replace your `setup()` call with a `vim.g.oil` assignment. For example, with
-[lazy.nvim](https://github.com/folke/lazy.nvim):
-
-```lua
--- before
-{
-  'stevearc/oil.nvim',
-  config = function(_, opts)
-    require('oil').setup(opts)
-  end,
-  opts = {
-    ...
-  }
-}
-
--- after
-{
-  'barrettruth/oil.nvim',
-  init = function()
-    vim.g.oil = {
-      columns = { "icon", "size" },
-      delete_to_trash = true,
-    }
-  end,
-}
-```
-
-**Q: Why "oil"?**
 
 **A:** From the [vim-vinegar](https://github.com/tpope/vim-vinegar) README, a quote by Drew Neil:
 
@@ -128,7 +111,7 @@ Plus, I think it's pretty slick ;)
 
 If you don't need those features specifically, check out the alternatives listed below
 
-**Q: Can oil display files as a tree view?**
+**Q: Can oil display files as a tree view**?
 
 **A:** No. A tree view would require a completely different methodology, necessitating a complete rewrite.
 
@@ -136,8 +119,6 @@ If you don't need those features specifically, check out the alternatives listed
 
 **A:**
 
-- [the original](https://github.com/stevearc/oil.nvim): the lesser-maintained but
-  official `oil.nvim`
 - [mini.files](https://github.com/nvim-mini/mini.nvim/blob/main/readmes/mini-files.md): Also supports cross-directory filesystem-as-buffer edits with a column view.
 - [vim-vinegar](https://github.com/tpope/vim-vinegar): The granddaddy of single-directory file browsing.
 - [dirbuf.nvim](https://github.com/elihunter173/dirbuf.nvim): Edit filesystem like a buffer, but no cross-directory edits.

doc/oil.txt

@@ -48,27 +48,6 @@ REQUIREMENTS                                                    *oil-requirement
 --------------------------------------------------------------------------------
 CONFIG                                                                *oil-config*
 
-Oil can be configured in two ways:
-
-1. The traditional `setup()` call: >lua
-    require("oil").setup({
-      -- your opts here
-    })
-<
-
-2. Declarative configuration via `vim.g.oil`, which does not require calling
-   `setup()`: >lua
-    vim.g.oil = {
-      -- your opts here
-    }
-<
-
-   When `vim.g.oil` is set, oil initializes automatically during plugin
-   loading. If `setup()` is called with explicit opts, those take precedence
-   over `vim.g.oil`.
-
-The full list of options with their defaults:
-
 >lua
     require("oil").setup({
       -- Oil will take over directory buffers (e.g. `vim .` or `:e src/`)

flake.lock

@@ -1,43 +0,0 @@
-{
-  "nodes": {
-    "nixpkgs": {
-      "locked": {
-        "lastModified": 1771207753,
-        "narHash": "sha256-b9uG8yN50DRQ6A7JdZBfzq718ryYrlmGgqkRm9OOwCE=",
-        "owner": "NixOS",
-        "repo": "nixpkgs",
-        "rev": "d1c15b7d5806069da59e819999d70e1cec0760bf",
-        "type": "github"
-      },
-      "original": {
-        "owner": "NixOS",
-        "ref": "nixpkgs-unstable",
-        "repo": "nixpkgs",
-        "type": "github"
-      }
-    },
-    "root": {
-      "inputs": {
-        "nixpkgs": "nixpkgs",
-        "systems": "systems"
-      }
-    },
-    "systems": {
-      "locked": {
-        "lastModified": 1681028828,
-        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
-        "owner": "nix-systems",
-        "repo": "default",
-        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
-        "type": "github"
-      },
-      "original": {
-        "owner": "nix-systems",
-        "repo": "default",
-        "type": "github"
-      }
-    }
-  },
-  "root": "root",
-  "version": 7
-}

flake.nix

@@ -1,29 +0,0 @@
-{
-  description = "oil.nvim — Neovim file explorer: edit your filesystem like a buffer";
-
-  inputs = {
-    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
-    systems.url = "github:nix-systems/default";
-  };
-
-  outputs =
-    {
-      nixpkgs,
-      systems,
-      ...
-    }:
-    let
-      forEachSystem = f: nixpkgs.lib.genAttrs (import systems) (system: f nixpkgs.legacyPackages.${system});
-    in
-    {
-      devShells = forEachSystem (pkgs: {
-        default = pkgs.mkShell {
-          packages = [
-            pkgs.prettier
-            pkgs.stylua
-            pkgs.selene
-          ];
-        };
-      });
-    };
-}

lua/oil/config.lua

@@ -406,7 +406,7 @@ local M = {}
 ---@field border? string|string[] Window border
 
 M.setup = function(opts)
-  opts = opts or vim.g.oil or {}
+  opts = opts or {}
 
   local new_conf = vim.tbl_deep_extend("keep", opts, default_config)
   if not new_conf.use_default_keymaps then

plugin/oil.lua

@@ -1,3 +0,0 @@
-if vim.g.oil ~= nil then
-  require("oil").setup()
-end

scripts/generate.py

@@ -0,0 +1,412 @@
+import os
+import os.path
+import re
+from dataclasses import dataclass, field
+from typing import Any, Dict, List
+
+from nvim_doc_tools import (
+    LuaParam,
+    LuaTypes,
+    Vimdoc,
+    VimdocSection,
+    generate_md_toc,
+    indent,
+    leftright,
+    parse_directory,
+    read_nvim_json,
+    read_section,
+    render_md_api2,
+    render_vimdoc_api2,
+    replace_section,
+    wrap,
+)
+from nvim_doc_tools.vimdoc import format_vimdoc_params
+
+HERE = os.path.dirname(__file__)
+ROOT = os.path.abspath(os.path.join(HERE, os.path.pardir))
+README = os.path.join(ROOT, "README.md")
+DOC = os.path.join(ROOT, "doc")
+VIMDOC = os.path.join(DOC, "oil.txt")
+
+
+def add_md_link_path(path: str, lines: List[str]) -> List[str]:
+    ret = []
+    for line in lines:
+        ret.append(re.sub(r"(\(#)", "(" + path + "#", line))
+    return ret
+
+
+def update_md_api():
+    api_doc = os.path.join(DOC, "api.md")
+    types = parse_directory(os.path.join(ROOT, "lua"))
+    funcs = types.files["oil/init.lua"].functions
+    lines = ["\n"] + render_md_api2(funcs, types, 2) + ["\n"]
+    replace_section(
+        api_doc,
+        r"^<!-- API -->$",
+        r"^<!-- /API -->$",
+        lines,
+    )
+    toc = ["\n"] + generate_md_toc(api_doc, max_level=1) + ["\n"]
+    replace_section(
+        api_doc,
+        r"^<!-- TOC -->$",
+        r"^<!-- /TOC -->$",
+        toc,
+    )
+    toc = add_md_link_path("doc/api.md", toc)
+    replace_section(
+        README,
+        r"^<!-- API -->$",
+        r"^<!-- /API -->$",
+        toc,
+    )
+
+
+def update_readme():
+    def get_toc(filename: str) -> List[str]:
+        subtoc = generate_md_toc(os.path.join(DOC, filename))
+        return add_md_link_path("doc/" + filename, subtoc)
+
+    recipes_toc = get_toc("recipes.md")
+
+    replace_section(
+        README,
+        r"^## Recipes$",
+        r"^#",
+        ["\n"] + recipes_toc + ["\n"],
+    )
+
+
+def update_md_toc(filename: str, max_level: int = 99):
+    toc = ["\n"] + generate_md_toc(filename, max_level) + ["\n"]
+    replace_section(
+        filename,
+        r"^<!-- TOC -->$",
+        r"^<!-- /TOC -->$",
+        toc,
+    )
+
+
+def update_config_options():
+    config_file = os.path.join(ROOT, "lua", "oil", "config.lua")
+    opt_lines = ['\n```lua\nrequire("oil").setup({\n']
+    opt_lines.extend(read_section(config_file, r"^\s*local default_config =", r"^}$"))
+    replace_section(
+        README,
+        r"^## Options$",
+        r"^}\)$",
+        opt_lines,
+    )
+
+
+@dataclass
+class ColumnDef:
+    name: str
+    adapters: str
+    editable: bool
+    sortable: bool
+    summary: str
+    params: List["LuaParam"] = field(default_factory=list)
+
+
+UNIVERSAL = [
+    LuaParam(
+        "highlight",
+        "string|fun(value: string): string",
+        "Highlight group, or function that returns a highlight group",
+    ),
+    LuaParam(
+        "align",
+        '"left"|"center"|"right"',
+        "Text alignment within the column",
+    )
+]
+TIME = [
+    LuaParam("format", "string", "Format string (see :help strftime)"),
+]
+COL_DEFS = [
+    ColumnDef(
+        "type",
+        "*",
+        False,
+        True,
+        "The type of the entry (file, directory, link, etc)",
+        UNIVERSAL
+        + [LuaParam("icons", "table<string, string>", "Mapping of entry type to icon")],
+    ),
+    ColumnDef(
+        "icon",
+        "*",
+        False,
+        False,
+        "An icon for the entry's type (requires nvim-web-devicons)",
+        UNIVERSAL
+        + [
+            LuaParam(
+                "default_file",
+                "string",
+                "Fallback icon for files when nvim-web-devicons returns nil",
+            ),
+            LuaParam("directory", "string", "Icon for directories"),
+            LuaParam(
+                "add_padding",
+                "boolean",
+                "Set to false to remove the extra whitespace after the icon",
+            ),
+            LuaParam(
+                "use_slow_filetype_detection",
+                "boolean",
+                "Set to true to detect filetypes by reading the first lines of each file (e.g. shebangs).",
+            ),
+        ],
+    ),
+    ColumnDef("size", "files, ssh, s3", False, True, "The size of the file", UNIVERSAL + []),
+    ColumnDef(
+        "permissions",
+        "files, ssh",
+        True,
+        False,
+        "Access permissions of the file",
+        UNIVERSAL + [],
+    ),
+    ColumnDef(
+        "ctime", "files", False, True, "Change timestamp of the file", UNIVERSAL + TIME + []
+    ),
+    ColumnDef(
+        "mtime", "files", False, True, "Last modified time of the file", UNIVERSAL + TIME + []
+    ),
+    ColumnDef(
+        "atime", "files", False, True, "Last access time of the file", UNIVERSAL + TIME + []
+    ),
+    ColumnDef(
+        "birthtime",
+        "files, s3",
+        False,
+        True,
+        "The time the file was created",
+        UNIVERSAL + TIME + [],
+    ),
+]
+
+
+def get_options_vimdoc() -> "VimdocSection":
+    section = VimdocSection("config", "oil-config")
+    config_file = os.path.join(ROOT, "lua", "oil", "config.lua")
+    opt_lines = read_section(config_file, r"^local default_config =", r"^}$")
+    lines = ["\n", ">lua\n", '    require("oil").setup({\n']
+    lines.extend(indent(opt_lines, 4))
+    lines.extend(["    })\n", "<\n"])
+    section.body = lines
+    return section
+
+
+def get_options_detail_vimdoc() -> "VimdocSection":
+    section = VimdocSection("options", "oil-options")
+    section.body.append(
+        """
+skip_confirm_for_simple_edits                  *oil.skip_confirm_for_simple_edits*
+    type: `boolean` default: `false`
+    Before performing filesystem operations, Oil displays a confirmation popup to ensure
+    that all operations are intentional. When this option is `true`, the popup will be
+    skipped if the operations:
+        * contain no deletes
+        * contain no cross-adapter moves or copies (e.g. from local to ssh)
+        * contain at most one copy or move
+        * contain at most five creates
+
+prompt_save_on_select_new_entry              *oil.prompt_save_on_select_new_entry*
+    type: `boolean` default: `true`
+    There are two cases where this option is relevant:
+    1. You copy a file to a new location, then you select it and make edits before
+       saving.
+    2. You copy a directory to a new location, then you enter the directory and make
+       changes before saving.
+
+    In case 1, when you edit the file you are actually editing the original file because
+    oil has not yet moved/copied it to its new location. This means that the original
+    file will, perhaps unexpectedly, also be changed by any edits you make.
+
+    Case 2 is similar; when you edit the directory you are again actually editing the
+    original location of the directory. If you add new files, those files will be
+    created in both the original location and the copied directory.
+
+    When this option is `true`, Oil will prompt you to save before entering a file or
+    directory that is pending within oil, but does not exist on disk.
+"""
+    )
+    return section
+
+
+def get_highlights_vimdoc() -> "VimdocSection":
+    section = VimdocSection("Highlights", "oil-highlights", ["\n"])
+    highlights = read_nvim_json('require("oil")._get_highlights()')
+    for hl in highlights:
+        name = hl["name"]
+        desc = hl.get("desc")
+        if desc is None:
+            continue
+        section.body.append(leftright(name, f"*hl-{name}*"))
+        section.body.extend(wrap(desc, 4))
+        section.body.append("\n")
+    return section
+
+
+def load_params(params: Dict[str, Any]) -> List[LuaParam]:
+    ret = []
+    for name, data in sorted(params.items()):
+        ret.append(LuaParam(name, data["type"], data["desc"]))
+    return ret
+
+
+def get_actions_vimdoc() -> "VimdocSection":
+    section = VimdocSection("Actions", "oil-actions", ["\n"])
+    section.body.append(
+        """The `keymaps` option in `oil.setup` allow you to create mappings using all the same parameters as |vim.keymap.set|.
+>lua
+    keymaps = {
+        -- Mappings can be a string
+        ["~"] = "<cmd>edit $HOME<CR>",
+        -- Mappings can be a function
+        ["gd"] = function()
+            require("oil").set_columns({ "icon", "permissions", "size", "mtime" })
+        end,
+        -- You can pass additional opts to vim.keymap.set by using
+        -- a table with the mapping as the first element.
+        ["<leader>ff"] = {
+            function()
+                require("telescope.builtin").find_files({
+                    cwd = require("oil").get_current_dir()
+                })
+            end,
+            mode = "n",
+            nowait = true,
+            desc = "Find files in the current directory"
+        },
+        -- Mappings that are a string starting with "actions." will be
+        -- one of the built-in actions, documented below.
+        ["`"] = "actions.tcd",
+        -- Some actions have parameters. These are passed in via the `opts` key.
+        ["<leader>:"] = {
+            "actions.open_cmdline",
+            opts = {
+                shorten_path = true,
+                modify = ":h",
+            },
+            desc = "Open the command line with the current directory as an argument",
+        },
+    }
+"""
+    )
+    section.body.append("\n")
+    section.body.extend(
+        wrap(
+            """Below are the actions that can be used in the `keymaps` section of config options. You can refer to them as strings (e.g. "actions.<action_name>") or you can use the functions directly with `require("oil.actions").action_name.callback()`"""
+        )
+    )
+    section.body.append("\n")
+    actions = read_nvim_json('require("oil.actions")._get_actions()')
+    actions.sort(key=lambda a: a["name"])
+    for action in actions:
+        if action.get("deprecated"):
+            continue
+        name = action["name"]
+        desc = action["desc"]
+        section.body.append(leftright(name, f"*actions.{name}*"))
+        section.body.extend(wrap(desc, 4))
+        params = action.get("parameters")
+        if params:
+            section.body.append("\n")
+            section.body.append("    Parameters:\n")
+            section.body.extend(
+                format_vimdoc_params(load_params(params), LuaTypes(), 6)
+            )
+
+        section.body.append("\n")
+    return section
+
+
+def get_columns_vimdoc() -> "VimdocSection":
+    section = VimdocSection("Columns", "oil-columns", ["\n"])
+    section.body.extend(
+        wrap(
+            'Columns can be specified as a string to use default arguments (e.g. `"icon"`), or as a table to pass parameters (e.g. `{"size", highlight = "Special"}`)'
+        )
+    )
+    section.body.append("\n")
+    for col in COL_DEFS:
+        section.body.append(leftright(col.name, f"*column-{col.name}*"))
+        section.body.extend(wrap(f"Adapters: {col.adapters}", 4))
+        if col.sortable:
+            section.body.extend(
+                wrap(f"Sortable: this column can be used in view_props.sort", 4)
+            )
+        if col.editable:
+            section.body.extend(wrap(f"Editable: this column is read/write", 4))
+        section.body.extend(wrap(col.summary, 4))
+        section.body.append("\n")
+        section.body.append("    Parameters:\n")
+        section.body.extend(format_vimdoc_params(col.params, LuaTypes(), 6))
+        section.body.append("\n")
+    return section
+
+
+def get_trash_vimdoc() -> "VimdocSection":
+    section = VimdocSection("Trash", "oil-trash", [])
+    section.body.append(
+        """
+Oil has built-in support for using the system trash. When
+`delete_to_trash = true`, any deleted files will be sent to the trash instead
+of being permanently deleted. You can browse the trash for a directory using
+the `toggle_trash` action (bound to `g\\` by default). You can view all files
+in the trash with `:Oil --trash /`.
+
+To restore files, simply move them from the trash to the desired destination,
+the same as any other file operation. If you delete files from the trash they
+will be permanently deleted (purged).
+
+Linux:
+    Oil supports the FreeDesktop trash specification.
+    https://specifications.freedesktop.org/trash/1.0/
+    All features should work.
+
+Mac:
+    Oil has limited support for MacOS due to the proprietary nature of the
+    implementation. The trash bin can only be viewed as a single dir
+    (instead of being able to see files that were trashed from a directory).
+
+Windows:
+    Oil supports the Windows Recycle Bin. All features should work.
+"""
+    )
+    return section
+
+
+def generate_vimdoc():
+    doc = Vimdoc("oil.txt", "oil")
+    types = parse_directory(os.path.join(ROOT, "lua"))
+    funcs = types.files["oil/init.lua"].functions
+    doc.sections.extend(
+        [
+            get_options_vimdoc(),
+            get_options_detail_vimdoc(),
+            VimdocSection("API", "oil-api", render_vimdoc_api2("oil", funcs, types)),
+            get_columns_vimdoc(),
+            get_actions_vimdoc(),
+            get_highlights_vimdoc(),
+            get_trash_vimdoc(),
+        ]
+    )
+
+    with open(VIMDOC, "w", encoding="utf-8") as ofile:
+        ofile.writelines(doc.render())
+
+
+def main() -> None:
+    """Update the README"""
+    update_config_options()
+    update_md_api()
+    update_md_toc(README, max_level=1)
+    update_md_toc(os.path.join(DOC, "recipes.md"))
+    update_readme()
+    generate_vimdoc()

scripts/main.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python
+import argparse
+import os
+import sys
+
+HERE = os.path.dirname(__file__)
+ROOT = os.path.abspath(os.path.join(HERE, os.path.pardir))
+DOC = os.path.join(ROOT, "doc")
+
+
+def main() -> None:
+    """Generate docs"""
+    sys.path.append(HERE)
+    parser = argparse.ArgumentParser(description=main.__doc__)
+    parser.add_argument("command", choices=["generate", "lint"])
+    args = parser.parse_args()
+    if args.command == "generate":
+        import generate
+
+        generate.main()
+    elif args.command == "lint":
+        from nvim_doc_tools import lint_md_links
+
+        files = [os.path.join(ROOT, "README.md")] + [
+            os.path.join(DOC, file) for file in os.listdir(DOC) if file.endswith(".md")
+        ]
+        lint_md_links.main(ROOT, files)
+
+
+if __name__ == "__main__":
+    main()

scripts/requirements.txt

@@ -0,0 +1,4 @@
+pyparsing==3.0.9
+black
+isort
+mypy

selene.toml

@@ -1 +0,0 @@
-std = 'vim'

tests/config_spec.lua

@@ -1,27 +0,0 @@
-local config = require("oil.config")
-
-describe("config", function()
-  after_each(function()
-    vim.g.oil = nil
-  end)
-
-  it("falls back to vim.g.oil when setup() is called with no args", function()
-    vim.g.oil = { delete_to_trash = true, cleanup_delay_ms = 5000 }
-    config.setup()
-    assert.is_true(config.delete_to_trash)
-    assert.equals(5000, config.cleanup_delay_ms)
-  end)
-
-  it("uses defaults when neither opts nor vim.g.oil is set", function()
-    vim.g.oil = nil
-    config.setup()
-    assert.is_false(config.delete_to_trash)
-    assert.equals(2000, config.cleanup_delay_ms)
-  end)
-
-  it("prefers explicit opts over vim.g.oil", function()
-    vim.g.oil = { delete_to_trash = true }
-    config.setup({ delete_to_trash = false })
-    assert.is_false(config.delete_to_trash)
-  end)
-end)