docs: centralize documentation into helpdoc (#15)
* 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 * build: remove docgen pipeline Problem: the Python docgen pipeline (scripts/generate.py, scripts/main.py, nvim_doc_tools) was designed for upstream's doc layout and is incompatible with the centralized helpdoc structure. It overwrites doc/oil.txt entirely and expects sections in README.md that no longer exist. Solution: delete the pipeline scripts (generate.py, main.py, requirements.txt), remove the update_docs CI job, and clean up the Makefile and .gitignore references. Linting and typechecking remain unchanged.
This commit is contained in:
Barrett Ruth
GitHub
parent
1712b6feb3
commit
3b930636e3
10 changed files with 363 additions and 1361 deletions
|
|
@ -1,412 +0,0 @@
|
|||
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()
|
||||
|
|
@ -1,31 +0,0 @@
|
|||
#!/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()
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
pyparsing==3.0.9
|
||||
black
|
||||
isort
|
||||
mypy
|
||||
Loading…
Add table
Add a link
Reference in a new issue