Metadata-Version: 2.5
Name: docsviewer
Version: 1.0.0
Summary: A desktop GUI for reading your project's docs/ folder, plus a scaffolder to create one.
Project-URL: Homepage, https://github.com/grish-ka/docsViewer
Project-URL: Issues, https://github.com/grish-ka/docsViewer/issues
Author-email: grish-ka <grishka.krot@gmail.com>
License: MIT
License-File: LICENSE
Keywords: docs,documentation,gui,markdown,pyside6,qt,viewer
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Win32 (MS Windows)
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.9
Requires-Dist: linkify-it-py>=2.0
Requires-Dist: markdown-it-py>=3.0
Requires-Dist: mdit-py-plugins>=0.4
Requires-Dist: pygments>=2.17
Requires-Dist: pyside6>=6.7
Requires-Dist: watchdog>=4.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# docsviewer

A small desktop app for reading a project's `docs/` folder, plus a scaffolder that
creates one. Point it at a folder of Markdown and get a sidebar, real rendered HTML,
search, and live reload — without leaving a native window.

```console
docsviewer init     # create ./docs with starter pages
docsviewer          # read them
```

## Features

- **Rendered Markdown** — GFM tables, task lists, footnotes, definition lists, and
  syntax-highlighted code via Pygments
- **Sidebar tree** — built from your folder structure, titled from each file's `# H1`
- **Full-text search** — across every document, with line-level hits
- **Live reload** — save a file in your editor and the open page updates, scroll
  position intact
- **Dark / light themes** — toggle with `Ctrl+D`, remembered between sessions
- **Sane links** — `[text](other.md)` navigates in-app, `https://` links open in your
  real browser

## Install

Requires Python 3.9+.

```console
git clone <your-repo-url>
cd docsViewer
python -m venv .venv
.venv\Scripts\activate          # Windows
pip install -e .
```

## Usage

```console
docsviewer                      # read ./docs, else the current folder
docsviewer path/to/docs         # read a specific folder
docsviewer notes/api.md         # open a single file
docsviewer . --here             # read this folder, ignoring its docs/
docsviewer init                 # scaffold ./docs
docsviewer init . --force       # overwrite existing starter files
```

A project directory resolves to its `docs/` subfolder when it has one — nearly every
project has a root `README.md`, so keying off "contains Markdown" would mean `docs/`
never won. Use `--here` to browse the folder itself.

`init` never overwrites your work — existing files are reported as `skipped` unless you
pass `--force`. The pages it writes are a copy of **this project's own `docs/` folder**,
so there is no separate templates directory to keep in sync.

Full documentation lives in [`docs/`](docs/README.md) — read it with the tool itself:

```console
docsviewer
```

Release notes are in [`CHANGELOG.md`](CHANGELOG.md).

### Keyboard shortcuts

| Shortcut | Action |
| --- | --- |
| `Ctrl+F` | Focus search |
| `Ctrl+D` | Toggle dark / light |
| `Ctrl+O` | Open another folder |
| `Ctrl+R` | Reload current page |
| `Alt+←` / `Alt+→` | Back / forward |
| `Ctrl+±` / `Ctrl+0` | Zoom in, out, reset |

## Development

```console
pip install -r requirements-dev.txt
pytest
ruff check .
```

The core modules (`renderer`, `tree`, `search`, `scaffold`) import no Qt, so the whole
test suite runs headlessly.

## Layout

| Module | Responsibility |
| --- | --- |
| `renderer.py` | Markdown → styled standalone HTML |
| `tree.py` | Folder scan, sorting, title extraction |
| `search.py` | In-memory full-text index |
| `scaffold.py` | The `init` command — copies `docs/` into new projects |
| `watcher.py` | watchdog events bridged onto the Qt event loop |
| `settings.py` | Persisted theme and window state |
| `app.py` | Main window and web view |
| `cli.py` | Argument parsing and entry point |

## License

MIT
