Add MkDocs documentation site with GitHub Pages deployment

Merge pull request #28 from sjmf/6-github-pages

Author: sjmf

.github/workflows/docs.yml

@@ -0,0 +1,32 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'README.md'
+      - 'CONTRIBUTING.md'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    name: Build and deploy documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+          cache: 'pip'
+
+      - name: Install MkDocs and Material theme
+        run: pip install mkdocs-material
+
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

.gitignore

@@ -18,6 +18,9 @@ kvm.dist
 uv.lock
 .venv/
 
+# MkDocs build output
+site/
+
 # Icon generation intermediate files
 assets/icon.iconset/
 assets/icon_*.png

docs/CONTRIBUTING.md

@@ -0,0 +1,186 @@
+# Contributing to KVM Serial
+
+Firstly, thank you for taking the time to contribute! I really appreciate it. ❤️
+
+This guide outlines how to contribute to the KVM Serial project, and helps ensure a smooth experience for everyone involved.
+
+If this project has been useful to you, please consider giving it a star. ⭐️
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [I Have a Question](#i-have-a-question)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [How to Contribute](#how-to-contribute)
+- [Reporting Bugs](#reporting-bugs)
+- [Pull Requests](#pull-requests)
+- [Testing](#testing)
+- [Documentation](#documentation)
+
+## Code of Conduct
+
+This project is committed to providing a welcoming and inclusive environment for all contributors. In summary: be decent to others in this space, act in good faith and assume good faith on others' parts, and conduct onself in a way which would be acceptable in the workplace.
+
+All participants should:
+
+- Be respectful and considerate in communications
+- Show empathy towards other community members
+- Accept constructive criticism gracefully
+- Focus on what is best for the project
+
+Unacceptable behavior includes:
+
+- Any conduct that would be inappropriate in a professional setting
+- Harassment of any kind
+- Discriminatory jokes and language
+- Personal or political attacks
+- Publishing others' private information
+- Trolling or insulting comments
+
+Violations should be reported to the project maintainer(s), who will take appropriate action.
+
+## I Have a Question
+
+Before asking a question:
+
+1. Read the [Home](index.md) page and any available documentation
+2. Search existing [Issues](https://github.com/sjmf/kvm-serial/issues) to see if your question has already been answered
+3. Search the internet for answers first: putting errors from the console into a search engine is a great place to start.
+
+If you still need clarification, please:
+
+- Open a [new issue](https://github.com/sjmf/kvm-serial/issues/new)
+- Provide as much context as possible: issues saying "it doesn't work", without further detail, will be closed saying "yes, it does".
+- Include relevant system information (OS, Python version, hardware details)
+
+## Getting Started
+
+### Forking the Repository
+
+You will need to fork the repository if you want to contribute via [Pull Request](#pull-requests).
+If that's you, read on!
+
+1. Fork the repository on GitHub
+2. Clone your fork locally:
+   ```bash
+   git clone https://github.com/your-username/kvm-serial.git
+   cd kvm-serial
+   ```
+3. Add the canonical repository to pull upstream changes:
+   ```bash
+   git remote add upstream https://github.com/sjmf/kvm-serial.git
+   ```
+
+## Development Setup
+
+To develop the code, there's a few steps to get set up:
+
+1. **Python Environment**: Ensure you have Python 3.8+ installed
+2. **Install Dependencies and Dev Dependencies**:
+   ```bash
+   pip install -e .
+   pip install '.[dev]'
+   ```
+3. **Install Pre-commit Hooks**: 
+   ```bash
+   pre-commit install
+   pre-commit run --all-files  # Run pre-commit on all files (optional)
+   ```
+
+Pre-commit hooks help to ensure that any code contributed follows the code style (`black`).
+
+## How to Contribute
+
+Contributions are fab! I really appreciate your being interested in this project. A contribution might be a bug report, a suggestion for a feature enhancement, addressing an oversight in the documentation or test suite, or just a well-structured question about how to use this project e.g. in a way we've not seen before.
+
+If you're considering giving back in the form of a contribution, here's the best way to do that:
+
+### Reporting Bugs
+
+#### Before Submitting a Bug Report
+
+Please ensure you're using the latest version of the software and verify that the issue is actually a bug rather than a configuration problem or user error. Search through existing [bug reports](https://github.com/sjmf/kvm-serial/issues?q=is%3Aissue+label%3Abug) to see if someone else has already encountered the same problem.
+
+When preparing your bug report, collect comprehensive information about your system environment. This should include your Python version and operating system, details about your hardware setup (particularly the CH9329 device and any connected cameras), your serial port configuration, complete error messages with stack traces, and clear steps that reliably reproduce the issue.
+
+#### How to Submit a Bug Report
+
+Open a [new issue](https://github.com/sjmf/kvm-serial/issues/new) with a clear, descriptive title that summarizes the problem. Describe both what behavior you expected to see and what actually happened. The most valuable bug reports include step-by-step reproduction instructions that allow maintainers to recreate the issue on their own systems. Include all the system and configuration information you collected, as this context is often crucial for diagnosing the root cause.
+
+### Pull Requests
+
+#### Before Creating a Pull Request
+
+1. **Create an Issue First**: For significant changes, create an issue to discuss the approach
+2. **Fork and Branch**: Create a feature branch from `main`
+3. **Stay Updated**: Regularly sync with upstream:
+   ```bash
+   git fetch upstream
+   git rebase upstream/main
+   ```
+
+#### Pull Request Guidelines
+
+1. **One Change Per PR**: Submit separate PRs for different features/fixes
+2. **Clear Description**: Explain what your PR does and why
+3. **Reference Issues**: Link to related issues with "Fixes #123"
+4. **Test Your Changes**: Ensure all tests pass
+5. **Follow Code Standards**: Use pre-commit hooks and linting
+
+### Commit Message Guidelines
+
+Examples:
+
+- `feat(video): add support for USB 3.0 cameras`
+- `fix(serial): handle port disconnection gracefully`
+- `docs(readme): update installation instructions`
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+python -m pytest
+
+# Run with coverage
+python -m pytest --cov=kvm_serial
+
+# Run specific test categories, e.g.:
+python -m pytest tests/kvm
+python -m pytest tests/backend
+```
+
+### Writing Tests
+
+Tests should be placed in the `tests/` directory. When writing new tests, focus on covering both successful operations and error conditions, ensuring that external dependencies like hardware devices are properly mocked to prevent actual device access during testing.
+
+Follow established patterns in the existing test suite, particularly around the use of context managers for patching and the helper methods provided by the base test class. The test structure emphasizes isolation and repeatability, so each test should be able to run independently without relying on state from other tests.
+
+Always check that tests pass in concert with other tests: tests can modify the global import state of the test environment, which can result in interference for example where a test accidentally makes an import which can then no longer be patched. I've gone to some lengths to check that tests don't interfere with each other (or skip them where they do), but it's far too easy to write a test where this can occur!
+
+## Documentation
+
+Documentation improvements are always welcome. Good documentation contributions focus on the user experience, and often come from people who have recently worked through setup or usage scenarios themselves.
+
+When updating documentation, prioritise clarity and accuracy over comprehensiveness. Include practical examples where they help illustrate concepts, and always test any instructions or code examples you add to ensure they work as described. If you're documenting new features, consider including both basic usage examples and more advanced scenarios.
+
+Documentation should be updated whenever functionality changes. This includes not just user-facing features, but also development processes, testing procedures, and troubleshooting information. The goal is to reduce friction for both users and future contributors.
+
+## Legal Notice
+
+By contributing to this project, you agree that:
+
+- You have authored 100% of the contributed content
+- You have the necessary rights to the content
+- Your contribution may be provided under the project license
+
+## Questions?
+
+If you have questions about contributing, feel free to:
+
+- Open an [issue](https://github.com/sjmf/kvm-serial/issues/new)
+- Contact the maintainers
+
+Thank you for contributing to KVM Serial! 🎉

docs/MODES.MD docs/MODES.mddocs/MODES.MD renamed to docs/MODES.md

@@ -0,0 +1,161 @@
+# Serial KVM Controller (CH9329)
+
+[![PyPI](https://img.shields.io/pypi/v/kvm-serial)](https://pypi.org/project/kvm-serial/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/sjmf/kvm-serial/blob/main/LICENSE.md)
+[![Black](https://img.shields.io/badge/code%20style-black-black)](https://github.com/sjmf/kvm-serial/actions/workflows/lint.yml)
+[![Run Tests](https://img.shields.io/github/actions/workflow/status/sjmf/kvm-serial/test.yml?label=Unit%20Tests)](https://github.com/sjmf/kvm-serial/actions/workflows/test.yml)
+[![codecov](https://img.shields.io/codecov/c/gh/sjmf/kvm-serial)](https://codecov.io/gh/sjmf/kvm-serial)
+
+A Software KVM, using the CH9329 UART Serial to USB HID controller.
+
+Control your computers using an emulated keyboard and mouse!
+
+This app and python module allows you to control to a second device using a CH9329 module (or cable)
+and a video capture device. You can find these from vendors on eBay and AliExpress for a low price.
+However, there is very little software support available for these modules, and CH9329
+protocol documentation is sparse.
+
+This software captures keyboard and mouse inputs from the local computer, sending these over a
+serial UART connection to the CH9329 USB HID module, which will output USB HID mouse and keyboard
+movements and scan codes to the remote computer.
+
+The `kvm_serial` package provides options for running the GUI, or as a script providing flexible options.
+
+<a href="https://github.com/sjmf/kvm-serial/releases/latest/"> <img align="left" src="https://raw.githubusercontent.com/sjmf/kvm-serial/main/assets/icon.png" alt="App icon" height="100" /></a>
+
+<hr />
+
+__[Download the latest release](https://github.com/sjmf/kvm-serial/releases/latest/)__ for Windows, Mac or Linux.
+
+*See [Installation](INSTALLATION.md) for information on installing serial drivers, if required.*
+
+
+## GUI Usage
+
+Run the GUI using the [executable for your platform](https://github.com/sjmf/kvm-serial/releases/latest/), or with Python using `python -m kvm_serial`.
+
+![KVM Window](https://wp.finnigan.dev/wp-content/uploads/2025/09/output-4.gif)
+*The Serial KVM window running on OSX, controlling a Windows remote machine*
+
+The module can be [installed from PyPI](https://pypi.org/project/kvm-serial/) (`pip install kvm-serial`),
+or locally from a cloned git repo (`pip install -e .`).
+
+The GUI app will do a lot of the work for you: it will enumerate video devices and serial ports,
+and give you a window to interact with the guest in. Application settings can be changed from the
+menus (File, Options, View), for example if the app doesn't select the correct devices by default.
+
+## Kit List
+
+This module requires a little bit of hardware to get going. You will need:
+
+* CH9329 module or cable
+* Video capture card (e.g. HDMI)
+
+You can likely get everything you need for under £30, which is incredible when compared to the
+price of a KVM crash cart adapter.
+
+### CH9329 module/cable assembled as cables
+
+_PLEASE NOTE: I am a hobbyist. I have no affiliation with any manufacturer developing or selling CH9329 hardware._
+
+[![Home-made serial KVM module](https://wp.finnigan.dev/wp-content/uploads/2023/11/mini-uart.jpg)](https://wp.finnigan.dev/?p=682)
+*A home-made serial KVM module: CH9329 module soldered to SILabs CP2102. CH340 works, too.*
+
+So, I don't have a specific vendor to recommend, but if you put "*CH9329 cable usb*" into a search
+engine, you will find the right thing. Just make sure what you buy has "CH9329" in the name: a USB-A
+to USB-A cable won't do, and can damage your machine.
+
+The modules have a USB-A male connector on one end, and serial connector on the other. The cables
+have USB-A both ends, as they are already put together and should pretty much be plug-and-play: just
+make sure it's the right way around. I just soldered a CH9329 module to a UART transceiver chip
+myself, as above.
+
+### Video capture card
+
+You also need a capture card that takes the display output from your remote machine, and presents it
+as a USB device to your local system. I found the "*UGREEN Video Capture Card HDMI to USB C Capture
+Device*" was a good balance of price versus value. The more you spend on a capture device, the more
+responsive your video feed will likely be (to a point). HDMI and VGA hardware is available.
+
+## Installing Python Dependencies
+
+_Note:_ These instructions are not required if using the executables, but you may need to do some other setup. See [Installation](INSTALLATION.md) for information on installing serial drivers.
+
+**Standard installation** (running the application from `pip`):
+
+```bash
+# OPTIONAL: Create and activate a Virtual environment
+python -m venv ./.venv
+./.venv/scripts/activate
+
+# Install the module from PyPI and run the GUI
+pip install kvm-serial
+python -m kvm-serial
+```
+
+OR using [`uv` package manager](https://docs.astral.sh/uv) (a faster alternative to pip, if available):
+*Note: `uv run` may not work on Windows. See [#15](https://github.com/sjmf/kvm-serial/issues/15).*
+
+```bash
+uv run kvm-gui
+```
+
+**Install from source** (for development- includes PyInstaller for building executables, pytest for testing, etc.):
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Script Usage
+
+A script called `control.py` is also provided for use directly from the terminal, so you can also control remotes from a headless environment! (e.g. Pi to Pi!)
+
+Packages must be installed first. Use your preferred python package manager. E.g.:
+
+
+
+Usage examples for the `control.py` script:
+
+```bash
+# Run using module
+python -m kvm_serial.control
+
+# Run using `uv`
+uv run kvm-control
+
+# Run with mouse and video support; use a Mac OSX serial port:
+python -m kvm_serial.control -ex /dev/cu.usbserial-A6023LNH
+
+# Run the script using keyboard 'tty' mode (no mouse, no video)
+python control.py --mode tty /dev/tty.usbserial0
+
+# Run using `pyusb` keyboard mode (which requires root):
+sudo python control.py --mode usb /dev/tty.usbserial0
+
+# Increase logging using --verbose (or -v), and use COM1 serial port (Windows)
+python control.py --verbose COM1
+```
+
+Use `python control.py --help` to view all available options. Keyboard capture and transmission is the default functionality of control.py: a couple of extra parameters are used to enable mouse and video. For most purposes, the default capture mode will suffice.
+
+Mouse capture is provided using the parameter `--mouse` (`-e`). It uses pynput for capturing mouse input and transmits this over the serial link simultaneously to keyboard input. Appropriate system permissions (Privacy and Security) may be required to use mouse capture.
+
+Video capture is provided using the parameter `--video` (`-x`). It uses OpenCV for capturing frames from the camera device. Again, system permissions for webcam access may need to be granted.
+
+See [Keyboard Modes](MODES.md) for more information on the various other options to the script.
+Implementations are provided for all the main python input capture methods.
+
+## Troubleshooting
+
+**Permissions errors on Linux**:
+if your system user does not have serial write permissions (resulting in a permission error), you can add your user to the `dialout` group: e.g. `sudo usermod -a -G dialout $USER`. You must fully log out of the system to apply the change.
+
+**Difficulty installing requirements**: If you get `command not found: pip` or similar when installing requirements, try: `python -m pip [...]` to run pip instead.
+
+## Acknowledgements
+With thanks to [@beijixiaohu](https://github.com/beijixiaohu), the author of the [ch9329Comm PyPi package](https://pypi.org/project/ch9329Comm/) and [GitHub repo](https://github.com/beijixiaohu/CH9329_COMM/) (in Chinese), some code of which is re-used under the MIT License.
+
+Thank you, once again, to everyone who has [contributed](CONTRIBUTING.md) to this project.
+
+## License
+(c) 2023-25 Samantha Finnigan and contributors (except where acknowledged) and released under [MIT License](https://github.com/sjmf/kvm-serial/blob/main/LICENSE.md).