`ovos-docs-viewer` - Documentation Index¶

In a nutshell

ovos-docs-viewer lets you read the OVOS documentation inside your terminal, without a web browser. Run ovos-docs-viewer technical to open this manual. Use the arrow keys to browse pages and press q to quit. It downloads the docs the first time and reuses them after that, so later visits work offline. See the Glossary for terms.

ovos-docs-viewer is a terminal-based documentation browser for OpenVoiceOS. It downloads Markdown documentation from GitHub. It then renders the docs inside the terminal using a Textual TUI with a file-tree sidebar and a Markdown viewer panel.

Minimal use: ovos-docs-viewer technical opens the technical manual in your terminal. Pass one of the documentation keys below as the single argument. The first run downloads and caches the docs. Later runs read from the cache. Use the arrow keys to walk the file tree, press Enter to open a file, and press q to quit. The tool is read-only. It needs network access only on first use, and every time for live-status.

How It Works¶

On first launch, the tool fetches documentation from a fixed set of GitHub sources and caches them under $XDG_DATA_HOME/ovos_docs/.
A Documentation Textual app opens with a split layout: a directory tree on the left (20% width) filtered to .md files only, and a MarkdownViewer on the right.
Navigate the tree and select a file to render it inline.
Press q to quit.

Downloaded sources are cached on disk. Later launches skip re-downloading (with an already cached, skipping message), except for live-status, which is always refreshed. Pass --refresh to wipe and re-download the selected set before launching.

The first launch of any key downloads every source

Regardless of which key you pass, Documentation.__init__ calls download_docs(), which loops over all sources. This includes the four zip archives (technical, messages, architecture, hivemind), the live-status/raspOVOS/installer READMEs, and all ~49 skill READMEs via download_skills(). It downloads each one that is not already cached. So ovos-docs-viewer technical on a clean machine populates the entire ovos_docs/ cache, not just the technical tree. The first run is slow and needs network access to all sources. Later runs only re-fetch live-status.

Installation¶

pip install ovos-docs-viewer

# or, from source:
git clone https://github.com/OpenVoiceOS/ovos-docs-viewer
cd ovos-docs-viewer
pip install -e .

Entry Point¶

ovos-docs-viewer DOCS

The console script ovos-docs-viewer maps to ovos_docs_viewer.ovos_docs:launch. DOCS is a single required argument. It must be one of the string keys below; an unknown key fails with a clean one-line error (exit code 2) before the TUI opens. --help describes every choice and the cache location.

Key	Source
`technical`	ovos-technical-manual (zip archive of the `master` branch, full `docs/` tree)
`messages`	message_spec (zip archive of `master`)
`hivemind`	HiveMind-community-docs (zip archive of `master`)
`live-status`	OVOS status page README (always re-downloaded)
`raspOVOS`	the raspOVOS image README
`installer`	ovos-installer README (`main` branch)
`skills`	`dev`-branch README files for ~49 official OVOS skills, one `.md` file per skill
`architecture`	architecture formal specifications (zip archive of `dev`; the markdown lives at the repo root, with the non-normative notes under `appendix/`)

Usage Examples¶

# Browse the OVOS technical manual
ovos-docs-viewer technical

# Browse skill documentation
ovos-docs-viewer skills

# Check live service status
ovos-docs-viewer live-status

# Browse HiveMind documentation
ovos-docs-viewer hivemind

# Browse the OVOS message bus specification
ovos-docs-viewer messages

Cache Location¶

Documentation is stored under:

$XDG_DATA_HOME/ovos_docs/
├── technical/docs/             ← ovos-technical-manual markdown tree (from zip)
├── messages/docs/              ← message spec markdown tree (from zip)
├── hivemind/docs/              ← HiveMind documentation tree (from zip)
├── live-status/docs/live-status.md  ← single README, always refreshed
├── raspOVOS/docs/raspOVOS.md        ← single README
├── installer/docs/installer.md      ← single README
└── skills/docs/                ← one .md per skill (e.g. ovos-skill-alerts.md)

Zip-archive sources (technical, messages, hivemind) keep their full docs/ tree; architecture keeps its repo-root markdown tree directly under <key>/. Single-README sources (live-status, raspOVOS, installer) are written as <key>/docs/<key>.md. $XDG_DATA_HOME resolves via ovos_utils.xdg_utils.xdg_data_home, typically ~/.local/share.

Seeing stale docs? Use --refresh

Cached sources are never re-fetched on their own (except live-status). If a page looks out of date, --refresh wipes and re-downloads the selected source only — other sets keep their cache:

ovos-docs-viewer --refresh technical

Substitute the relevant key (messages, hivemind, skills, …) for technical, or remove the whole ovos_docs/ directory to refresh everything at once.

UI Keybindings¶

Key	Action
Arrow keys / mouse	Navigate directory tree
Enter	Open selected file in Markdown viewer
`q`	Quit the application

Dependencies¶

Package	Role
`textual`	TUI framework (App, DirectoryTree, MarkdownViewer)
`click`	CLI argument parsing
`requests`	HTTP download of documentation
`ovos_utils`	XDG path resolution (`xdg_data_home`)

Read next: Hardware Integrators Related: OVOS Repository Index · Command-line Tools · Contributing

ovos-docs-viewer - Documentation Index¶