Initial commit: Tailscale Funnel plugin for OctoPrint with build documentation

octoprint_tailscale_funnel/BUILDING.md

@@ -0,0 +1,125 @@
+# Building the Tailscale Funnel Plugin
+
+This document describes how to build the Tailscale Funnel plugin for OctoPrint from source.
+
+## Prerequisites
+
+Before building the plugin, ensure you have the following installed on your system:
+
+* Python 3.7 or higher
+* pip (Python package installer)
+* git (optional, for version control)
+
+## Build Process
+
+### 1. Clone the Repository
+
+If you haven't already, clone the repository:
+
+```bash
+git clone https://gitea.elpatron.me/elpatron/octo-funnel.git
+cd octo-funnel
+```
+
+### 2. Create a Virtual Environment
+
+It's recommended to use a virtual environment to isolate the build dependencies:
+
+```bash
+python3 -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+```
+
+### 3. Install Build Dependencies
+
+Install the required Python packages:
+
+```bash
+pip install setuptools wheel octoprint
+```
+
+### 4. Build the Plugin
+
+Navigate to the plugin directory and run the setup script:
+
+```bash
+cd octoprint_tailscale_funnel
+python setup.py sdist bdist_wheel
+```
+
+This will create distribution files in the `dist/` directory:
+- A source distribution (tar.gz)
+- A wheel distribution (whl)
+
+### 5. Create OctoPrint-Compatible Package
+
+OctoPrint's plugin manager expects a zip file with a specific naming convention. Create it by copying and renaming the tar.gz file:
+
+```bash
+cp dist/octoprint_tailscale_funnel-*.tar.gz dist/OctoPrint-Tailscale-Funnel-*.zip
+```
+
+The resulting file `OctoPrint-Tailscale-Funnel-*.zip` can be uploaded to OctoPrint through the plugin manager.
+
+## Directory Structure
+
+After a successful build, the project directory will contain:
+
+```
+octoprint_tailscale_funnel/
+├── dist/
+│   ├── octoprint_tailscale_funnel-<version>.tar.gz
+│   ├── octoprint_tailscale_funnel-<version>-py3-none-any.whl
+│   └── OctoPrint-Tailscale-Funnel-<version>.zip
+├── build/
+│   └── ... (temporary build files)
+├── OctoPrint_Tailscale_Funnel.egg-info/
+│   └── ... (package metadata)
+└── ... (source files)
+```
+
+## Troubleshooting
+
+### ImportError: No module named 'octoprint_setuptools'
+
+If you encounter this error, make sure you've installed OctoPrint in your virtual environment:
+
+```bash
+pip install octoprint
+```
+
+### Permission Errors
+
+If you encounter permission errors during installation, you may need to use the `--user` flag:
+
+```bash
+pip install --user setuptools wheel octoprint
+```
+
+### Package Directory Issues
+
+If you see warnings about package directories, ensure the setup.py file is correctly configured with the appropriate package structure.
+
+## Cleaning Up
+
+To clean up build artifacts:
+
+```bash
+rm -rf build/ dist/ *.egg-info/
+```
+
+This will remove all generated files and allow you to rebuild from scratch.
+
+## Versioning
+
+The plugin version is defined in `setup.py`. To release a new version:
+
+1. Update the `plugin_version` variable in `setup.py`
+2. Rebuild the plugin following the steps above
+3. The new version will be reflected in the generated filenames
+
+## Additional Resources
+
+* [OctoPrint Plugin Development Documentation](https://docs.octoprint.org/en/master/plugins/getting-started.html)
+* [Tailscale Documentation](https://tailscale.com/kb/)
+* [Python Packaging Documentation](https://packaging.python.org/)