数据分析CLI数据可视化【免费下载链接】visidataA terminal spreadsheet multitool for discovering and arranging data项目地址https://gitcode.com/gh_mirrors/vi/visidata点击查看免费下载导读VisiData 是一个终端表格数据探索工具其内置帮助体系GuideSheet 指南、manpage、侧边栏帮助字符串全部以 Markdown 与一种自定义的显示属性语法撰写再在运行时由MissingAttrFormatter与CommandHelpGetter/OptionHelpGetter动态渲染。本文以仓库中的 dev/DOCS.md 为骨架结合 visidata/guide.py、visidata/man/vd.inc 与visidata/guides/下真实指南文件完整讲解 VisiData 文档的语法、模板、写作约定与构建流程帮助你为 VisiData或其插件编写风格一致、可被 GuideSheet 正确渲染并进入 manpage 的内置帮助文档。一、文档体系总览一份源码三处呈现VisiData 的内置文档遵循单一来源、多端呈现的设计这一点在dev/DOCS.md开头即有明确说明docs/man.md由 manpage 源文件visidata/man/vd.inc经dev/mkman.sh生成。修改时应编辑vd.inc而非生成的man.md。从仓库实际结构看文档体系分为三层层源文件呈现位置manpagevisidata/man/vd.inc构建产物vd.1、visidata.1、vd.txt可用g^H在 VisiData 内查看GuideSheet 指南visidata/guides/*.mdVisiData 内置的 Guide IndexSpace打开中的各篇指南helpstring / 侧边栏散落在visidata/*.py各命令与选项定义处命令帮助、Options Sheet 等其中指南文件采用 Markdown {help.commands.*}、{help.options.*}占位符与 manpage 的 roff 源完全分离但语义互补。dev/DOCS.md中VisiData 支持基本 Markdown# Headings、bold、italics、code snippets、underscore一条正是针对 GuideSheet 指南而言。二、核心语法一显示属性Display Attribute标记VisiData 有自己的显示属性语法用于在纯文本文档中注入可交互、带颜色的富文本。dev/DOCS.md给出了两个规范示例。2.1 可点击链接[:onclick url]text[/]将text格式化为可点击 URL点击后会在$BROWSER中打开。仓库中的真实用法例如 visidata/guide.py 的 Guide Index 简介We love contributions: [:onclick https://visidata.org/docs/api/guides]https://visidata.org/docs/api/guides[/].2.2 颜色与语义色[:red on black]sentence[/]将sentence渲染为黑底红字。:之后可以使用任意颜色选项例如[:warning]、[:error]、[:menu]。dev/DOCS.md特别强调尽可能使用[:semantic_color]而非硬编码颜色。这对应 VisiData 的主题/语义色机制在 GuideSheet 与帮助文本中语义色会跟随用户主题而硬编码颜色不会。仓库中常见的语义色标记还包括[:keystrokes]、[:longname_guide]、[:code]、[:onclick]等例如 visidata/guide.py 中动态生成的命令条目[:code]{binding}[/] ([:longname_guide]{longname}[/]) to {helpstr}三、核心语法二{vd.options.*}选项值内联VisiData 会替换{vd.options.disp_selected_note}为当前选项值——例如disp_selected_note的默认值是。任何选项值都可以用{vd.options.optname}引用。dev/DOCS.md给出了这条规则的动机这是确保正确选项被展示的好办法即使使用者已经修改了选项值。也就是说文档中不要写死、:这类符号而应通过占位符引用选项让文档随用户配置自适应。这一替换由 visidata/utils.py 的MissingAttrFormatter完成——它继承自string.Formatter在字段缺失时不会抛KeyError/AttributeError而是原样保留{field_name}见utils.py#L195-L199从而避免因选项重命名导致的渲染崩溃。四、核心语法三{help.commands.*}与{help.options.*}模板这是 GuideSheet 文档最核心的机制不要在指南里手写按键与帮助字符串而是用占位符让系统生成。4.1 命令占位符dev/DOCS.md规定命令应使用{help.commands.longname}展开为如下规范格式- keystroke (longname) to command helpstring.对应实现位于 visidata/guide.py 的CommandHelpGetter它通过__getattr__接收占位符中的 longname在HelpSheet的反向绑定表revbinds中查找实际按键再拼接命令帮助字符串若命令接收输入还会追加input或具体输入类型。例如 visidata/guides/MovementGuide.md 中的一行- {help.commands.go_down}渲染后即成为↓ (go_down) to move cursor down one row.这类条目。按键紧跟项目符号规范中明确keystroke 紧跟在 bullet 之后。VisiData 文档与 helpstring 中不要说 Press 或 Use。4.2 选项占位符选项应使用如下模式列出dev/DOCS.md原文- [:onclick options-sheet option name]option name[/] to option helpstring (default: option default value).同样地更推荐用{help.options.option-name}展开而不是手写。实现见 visidata/guide.py 的OptionHelpGetterreturn f[:onclick options-sheet {optname}][:longname_guide]{optname}[/][/]: {opt.helpstr} (default: {opt.value})它把选项名变成指向 Options Sheet 的可点击链接并自动附带帮助字符串与当前默认值。真实示例如 visidata/guides/FrequencyTable.md- {help.options.disp_histogram} - {help.options.histogram_bins} - {help.options.numeric_binning}4.3 渲染流水线GuideSheet 的加载逻辑visidata/guide.py展示了完整流水线读取visidata/guides/Name.md源文本按---解析 front matter如sheettype元数据用于确定命令查找的 Sheet 类构造helper AttrDict(commandsCommandHelpGetter(...), optionsOptionHelpGetter())用MissingAttrFormatter().format(guidetext, helphelper, vdvd)展开全部{help.*}占位符按 78 列折行wraptext后逐行进入 GuideSheet 表格。五、写作风格规范dev/DOCS.md后半部分是一组精炼的写作约定是评审 VisiData 文档提交的核心 checklist规范说明人称教程之外的文档不得使用第二人称you/yours语境不写 In VisiData默认用户已在 VisiData 内用词不使用多余的填充词用更简单的词与语法面向 ESL 读者动词用不定式避免将来时与条件句用主动语态术语使用既定词汇如 command 而非 operation/action语义色能用[:semantic_color]就不用硬编码颜色按键样式指南中用户会实际输入的内容keystroke、longname、CLI 选项用[:keystrokes]用户看到的输出不用修饰键写作CtrlX、AltX、ShiftX禁用脱字符记法^X前缀键前缀修饰键与基础键之间用空格分隔g Enter、z ShiftF、gz Enter选项名行文中选项名加options.前缀如options.numeric_binning选项表中列头已写 option 时不加详略匹配周围条目的详细程度loader 参考新增通常只需命令摘要描述对象描述用户可见行为而非实现细节。例如写 在频率表上撤销也会在源表上撤销而非 两张表共享同一个撤销点表格 vs 列表每行可独立成条时优先用列表而非多列表格标点仅用 ASCII 标点禁用 em-dash、en-dash、弯引号、Unicode 省略号用-或:标题小节标题用简短名词短语或祈使句如 Sort by one column、Hide and Unhide columns不用完整句子或 How to X 式标题开场白标题自解释时跳过开场段最多一句简短 setup描述内容描述命令做什么而非界面长什么样屏幕底部出现提示属于 UI 叙述应避免模糊语避免 (when available)、(if possible) 这类含糊括注这些约定在 visidata/guides/ColumnsGuide.md 中有很好的示范——其小节标题均为名词短语Resize the current column、Hide and Unhide columns全文无第二人称选项与命令均通过占位符引用。六、manpage 生成链路vd.inc→mkman.sh6.1 构建流程dev/mkman.sh 是 manpage 的生成脚本通过make man触发其关键步骤为将visidata/man/下的 roff 源复制到/tmp/visidata_manpages构建目录运行 visidata/man/parse_options.py从visidata.options运行时注册表中扫描所有选项自动生成vd-cli.incCLI 选项段与vd-opts.inc显示选项段两个 roff include用soelim -rt -I展开vd.inc中的.soinclude得到vd-pre.1用preconvUTF-8 转换生成vd.1与visidata.1用man渲染出vd.txt。脚本头部还注明了外部依赖soelim、preconv来自 groff与man。6.2 选项自动扫描parse_options.py展示了 manpage 中 CLI 选项如何与源码保持同步它遍历visidata.options的全部键读取每个选项的名称、类型、默认值与 helpstring按bool与其他类型分别套用 roff 模板。由此可以推断新增/修改选项的 helpstring 后重新运行构建manpage 会自动反映变更无需手工维护选项列表。6.3 主源文件结构visidata/man/vd.inc 是手写的 roff 主源涵盖SYNOPSIS普通启动、--play回放模式、以及toplevel:subsheet:col:row光标定位启动语法GLOBAL COMMANDS从退出^Q、q、Q、gq、移动h/j/k/l、G/gg、^B/^F、zz、搜索/、?、n/N、z/表达式搜索到列操作、行选择、排序、编辑、数据工具包、可视化与分屏命令的完整按键参考INTERNAL SHEETS / METASHEETS / DERIVED SHEETSDirectory Sheet、Guide Index、Memory Sheet、Columns SheetShiftC、Sheets SheetShiftS、Options SheetShiftO、CommandLogShiftD、Threads SheetCtrlT、Frequency TableShiftF、Describe SheetShiftI、Pivot TableShiftW、Melted SheetShiftM等COMMANDLINE OPTIONS-f/--filetype、-of、-d、-y/--confirm、-ro/--overwrite、-N/--nothing、-Plongnamepreplay、sheet:col:row定位、--guides等随后.so vd-cli.inc引入自动生成的完整 CLI 选项EXAMPLESvd foo.tsv、vd -f ddw、vd -f sqlite bar.db、vd -b countries.fixed -o countries.tsv格式转换、--play回放、管道ls -l | vd -f fixed --skip 1 --header 0、多文件光标定位等实用示例FILES$HOME/.visidatarc启动时被exec()可设置选项、bindkey、定义函数并经vd.aggregator()注册聚合器SUPPORTED SOURCEStsv、csv、fixed、json/jsonl、sqlite、http 及 zip/gz/bz2/xz/zstd 在线解压。这些内容与dev/DOCS.md共同构成 VisiData 的完整内置文档体系——前者是书写规范后者是内容本体。七、撰写一份合规指南的实操流程结合上述规范为 VisiData 新增或修订一篇指南或插件自带指南的推荐流程为选型在 visidata/guides/ 下新建GuideName.md或在插件包内附带同名文件GuideSheet 通过vd.addGuide(name)从visidata/guides/{name}.md加载visidata/guide.py搭骨架用#标题开篇小节标题使用名词短语或祈使句标题自解释时不要写开场段引用命令凡涉及按键/命令一律写- {help.commands.longname}不要手写按键——渲染器会从 HelpSheet 自动匹配当前按键绑定引用选项写- {help.options.opt-name}渲染为带默认值、可点击跳转 Options Sheet 的条目富文本需要链接时用[:onclick url]text[/]需要强调时用语义色[:warning]、[:error]、[:menu]而非硬编码颜色用户会键入的内容用[:keystrokes]包裹语言自检无第二人称、无 In VisiData、无填充词、动词不定式、主动语态、全 ASCII 标点验证启动vd用Space打开 Command Palette 执行open-guide-index进入新指南查看{help.*}是否正确展开修改 visidata/man/vd.inc 后运行make man重新生成 manpage。参考来源规范正文dev/DOCS.md渲染实现visidata/guide.py、visidata/utils.py指南样例visidata/guides/MovementGuide.md、visidata/guides/ColumnsGuide.md、visidata/guides/FrequencyTable.md、visidata/guides/ClipboardGuide.mdmanpage 生成dev/mkman.sh、visidata/man/vd.inc、visidata/man/parse_options.py赞分享数据分析CLI数据可视化【免费下载链接】visidataA terminal spreadsheet multitool for discovering and arranging data项目地址https://gitcode.com/gh_mirrors/vi/visidata点击查看免费下载相关推荐FSPagerView代码文档规范编写易读易维护的API文档FSPagerView代码文档规范编写易读易维护的API文档 在iOS开发中优雅的轮播图Banner View和页面滑动组件是提升用户体验的关键元素。F移动开发UI组件Zinx代码注释规范提升可维护性的文档编写指南Zinx代码注释规范提升可维护性的文档编写指南 引言为什么注释规范对Zinx至关重要 你是否曾打开一个开源项目却因混乱的注释而无从下手作为基于Gola后端Pydantic AI 文档编写规范为读者价值写作的文档、Docstring 与代码注释指南Pydantic AI 文档编写规范为读者价值写作的文档、Docstring 与代码注释指南 本文是 Pydantic AI 仓库内部《Documentati人工智能大模型AI Agent工具调用MCP Clients上一篇手把手用 kohya_ss 零基础训练 Stable Diffusion LoRA 模型下一篇如何快速优化游戏性能3个简单步骤提升流畅度创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考