From 12c4e00ece7b4ea9d2497750a8638789fad42a22 Mon Sep 17 00:00:00 2001 From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com> Date: Fri, 13 Mar 2026 15:34:48 -0400 Subject: [PATCH] feat: Implement Doc-Sync engine for automated multi-language documentation --- README.md | 12 +++ docs/{ => de}/docker.md | 0 docs/{ => de}/templates.md | 0 docs/{ => de}/troubleshooting.md | 0 docs/{ => de}/usage.md | 0 docs/en/docker.md | 16 ++++ docs/en/templates.md | 14 ++++ docs/en/troubleshooting.md | 60 ++++++++++++++ docs/en/usage.md | 130 ++++++++++++++++++++++++++++++ docs/es/docker.md | 16 ++++ docs/es/templates.md | 14 ++++ docs/es/troubleshooting.md | 60 ++++++++++++++ docs/es/usage.md | 130 ++++++++++++++++++++++++++++++ docs/templates/docker.md | 16 ++++ docs/templates/templates.md | 14 ++++ docs/templates/troubleshooting.md | 60 ++++++++++++++ docs/templates/usage.md | 130 ++++++++++++++++++++++++++++++ voxvera/cli.py | 50 ++++++++++++ 18 files changed, 722 insertions(+) rename docs/{ => de}/docker.md (100%) rename docs/{ => de}/templates.md (100%) rename docs/{ => de}/troubleshooting.md (100%) rename docs/{ => de}/usage.md (100%) create mode 100644 docs/en/docker.md create mode 100644 docs/en/templates.md create mode 100644 docs/en/troubleshooting.md create mode 100644 docs/en/usage.md create mode 100644 docs/es/docker.md create mode 100644 docs/es/templates.md create mode 100644 docs/es/troubleshooting.md create mode 100644 docs/es/usage.md create mode 100644 docs/templates/docker.md create mode 100644 docs/templates/templates.md create mode 100644 docs/templates/troubleshooting.md create mode 100644 docs/templates/usage.md diff --git a/README.md b/README.md index 9c8c853..81a0918 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,18 @@ Generate printable flyers with QR codes linking to Tor (.onion) hidden services, --- +## Documentation + +VoxVera is available in multiple languages. Select your preferred language for the detailed usage guide: + +| Language | Documentation | +| :--- | :--- | +| πŸ‡ΊπŸ‡Έ **English** | [docs/en/usage.md](docs/en/usage.md) | +| πŸ‡ͺπŸ‡Έ **EspaΓ±ol** | [docs/es/usage.md](docs/es/usage.md) | +| πŸ‡©πŸ‡ͺ **Deutsch** | [docs/de/usage.md](docs/de/usage.md) | + +--- + ## Key Features * **Interactive setup**: `voxvera init` prompts for metadata or extracts from a PDF form. When editing body text, a small Tkinter GUI window opens with existing content pre-filled, falling back to the user's `$EDITOR` if the GUI isn't available. diff --git a/docs/docker.md b/docs/de/docker.md similarity index 100% rename from docs/docker.md rename to docs/de/docker.md diff --git a/docs/templates.md b/docs/de/templates.md similarity index 100% rename from docs/templates.md rename to docs/de/templates.md diff --git a/docs/troubleshooting.md b/docs/de/troubleshooting.md similarity index 100% rename from docs/troubleshooting.md rename to docs/de/troubleshooting.md diff --git a/docs/usage.md b/docs/de/usage.md similarity index 100% rename from docs/usage.md rename to docs/de/usage.md diff --git a/docs/en/docker.md b/docs/en/docker.md new file mode 100644 index 0000000..318d35d --- /dev/null +++ b/docs/en/docker.md @@ -0,0 +1,16 @@ +# Docker Usage + +A prebuilt image containing Tor, OnionShare and the `voxvera` CLI is published to +`ghcr.io/voxvera/voxvera`. + +```bash +# pull the image +docker pull ghcr.io/voxvera/voxvera:latest + +# run voxvera quickstart with flyers stored in ./flyers +mkdir -p flyers +docker run -it --rm -v "$(pwd)/flyers:/flyers" ghcr.io/voxvera/voxvera +``` + +The container uses `/flyers` as the working directory and runs `voxvera quickstart` +by default. All generated flyer files will appear in the mounted `flyers` folder. diff --git a/docs/en/templates.md b/docs/en/templates.md new file mode 100644 index 0000000..f299c24 --- /dev/null +++ b/docs/en/templates.md @@ -0,0 +1,14 @@ +# Flyer Templates + +Pre-built flyer templates live in the `templates/` directory. Use the CLI to copy one with: + +```bash +voxvera init --template +``` + +This will create a new folder under `dist/` named `-` containing the template files. + +Available templates: + +- **blank** – minimal placeholder files, also used when extracting fields from a PDF. +- **voxvera** – example flyer showcasing the VoxVera project. diff --git a/docs/en/troubleshooting.md b/docs/en/troubleshooting.md new file mode 100644 index 0000000..e75be08 --- /dev/null +++ b/docs/en/troubleshooting.md @@ -0,0 +1,60 @@ +# Troubleshooting + +This page collects common issues encountered when hosting or accessing flyers. + +## Tor connectivity +- Ensure Tor is allowed through your firewall. On systems using `ufw` you may need to run `sudo ufw allow tor`. +- Some networks block Tor entirely. If you cannot reach onion services, try connecting over a different network or use a Tor bridge. + +## Tor port detection + +`voxvera serve` auto-detects Tor by probing common ports (9050/9150 for SOCKS, 9051/9151 for control). If detection fails -- for example when Tor runs on non-standard ports -- you can override with environment variables: + +```bash +TOR_SOCKS_PORT=19050 TOR_CONTROL_PORT=19051 voxvera serve +``` + +If no running Tor is found, the defaults (9050/9051) are used and OnionShare will attempt to connect on those ports. + +## Firewall rules +- If `voxvera serve` fails to start OnionShare, verify that outbound connections on ports 9001 and 80 are permitted. +- Corporate or university firewalls can block the hidden service ports required by Tor. + +## SELinux +- On SELinux-enabled distributions you may see `permission denied` errors when OnionShare writes to the `host` directory. +- Run `sudo chcon -Rt svirt_sandbox_file_t host` or disable SELinux enforcement for the folder. + +## OnionShare crashes +If `voxvera serve` prints "OnionShare exited unexpectedly", check the log file +`host//onionshare.log` for details. Common causes: + +- Tor is not running (`sudo systemctl start tor`) +- A port conflict with another service +- Missing `onionshare-cli` (run `voxvera check`) + +## Onion URL changed unexpectedly +The onion URL is tied to the Ed25519 keypair stored in +`host//.onionshare-session`. If this file is deleted, a new +keypair (and URL) will be generated on the next `voxvera serve`. The +`voxvera import` command preserves this file automatically, but manual +deletion of the `host/` directory will destroy it. + +## QR codes not generated +If `voxvera build` reports "No URLs configured yet", this is expected before the first `voxvera serve`. QR codes for tear-off links are generated automatically once the .onion address is known. QR codes for the content link are generated if you provided a URL during `voxvera init`. + +## Electron GUI +If `npm start` fails with `spawn voxvera ENOENT`, the `voxvera` command is not in your `PATH`. Install it with `pipx install git+https://github.com/PR0M3TH3AN/VoxVera.git` or run `./install.sh` from the repository. + +## Missing dependencies +Run `voxvera check` to verify your setup. The command checks for required +Python packages (`qrcode`, `Pillow`, `jsmin`, `htmlmin`, `pypdf`) and +external tools (`onionshare-cli`), then prints a summary of anything +missing. To install everything: + +```bash +# Recommended: use the install script (handles Tor + OnionShare too) +curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash + +# Or reinstall just the Python package +pipx install --force 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main' +``` diff --git a/docs/en/usage.md b/docs/en/usage.md new file mode 100644 index 0000000..833e23b --- /dev/null +++ b/docs/en/usage.md @@ -0,0 +1,130 @@ +# Detailed Usage + +This guide covers common CLI workflows. See `docs/docker.md` for Docker instructions and `docs/templates.md` for available flyer templates. + +## Prerequisites + +VoxVera is designed to be highly portable and requires minimal system dependencies. + +### 1. Standalone Binaries (Recommended) +You can download standalone, zero-dependency binaries for your operating system: +- **Linux:** `voxvera-linux` +- **Windows:** `voxvera-windows.exe` +- **macOS:** `voxvera-macos` + +These binaries include everything needed to run VoxVera (except `onionshare-cli`). + +### 2. One-Line Installer +Alternatively, install via our automated script: + +```bash +curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash +``` + +### 3. Manual Python Install +If you prefer to run from source: + +```bash +pipx install 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main' +sudo apt install tor onionshare-cli # Debian/Ubuntu +``` + +## Step-by-Step + +1. **Initialize:** Run `voxvera init` and follow the prompts. You will be asked to select your language first. +2. **Build:** Generate the flyer assets. Every build automatically creates a `voxvera-portable.zip` in the flyer's folder, allowing others to download the full tool directly from your flyer. + ```bash + voxvera build + ``` +3. **Serve:** Publish the flyer over Tor: + ```bash + voxvera serve + ``` + This automatically detects your Tor instance, starts OnionShare, and writes the generated .onion address into the flyer's tear-off links. + +## Language Support + +VoxVera is fully localized. You can change your language preference permanently using either the interactive selector or a direct shortcut: + +- **Interactive Selector:** `voxvera lang` +- **Direct Shortcut:** `voxvera --lang de` (sets preference to German) + +### Supported Languages: +- **English:** `en` +- **Spanish:** `es` (alias: `--idioma`) +- **German:** `de` (alias: `--sprache`) + +You can also force a specific language for a single command without changing your permanent preference: +- **English:** `voxvera --lang en check` +- **German:** `voxvera --sprache de check` +- **Spanish:** `voxvera --idioma es check` + +The generated flyers automatically detect the visitor's browser language and switch the UI text accordingly. + +## Server Management + +Manage multiple flyers and their Tor identities from a single interactive menu: + +```bash +voxvera manage +``` + +Features: +- **--- Create New Site/Flyer ---**: Start the full setup sequence. +- **Start/Stop All Sites**: Launch or shut down every flyer in your fleet at once. +- **Real-time Status**: View active `.onion` URLs and Tor bootstrapping progress indicators. +- **Individual Control**: Export specific sites to ZIP or delete them. + +## Universal Mirroring (Viral Distribution) + +To ensure VoxVera remains accessible even if central repositories are censored, every flyer acts as a mirror for the tool. + +When you host a flyer, the **"Download Tool & Source"** button on the landing page provides a `voxvera-portable.zip` containing: +- The full source code and all supported languages. +- All Python dependencies (pre-vendored). +- Cross-platform Tor binaries. + +This allows anyone who scans your flyer to become a new distributor of the VoxVera tool. + +## Export & Backup + +Back up your unique Tor identities (so your `.onion` URL never changes) or move your flyers to another machine. + +- **Export a single site**: `voxvera export ` +- **Export all sites**: `voxvera export-all` + +**Storage location:** All exports are saved to `~/voxvera-exports/` on all platforms. + +## Import & Recovery + +Restore your entire setup on a new machine by moving your ZIP files to `~/voxvera-exports/` and running: + +```bash +voxvera import-multiple +``` + +## Portability & Offline Use + +If you need to run VoxVera on a machine without internet access, you can "vendorize" the dependencies first: + +```bash +voxvera vendorize +``` + +This downloads all required Python libraries into `voxvera/vendor/`. The tool will then prioritize these local files, allowing it to run without `pip install`. + +## Batch Import (JSON) + +To bulk-generate flyers from multiple JSON configuration files, place them in the `imports/` directory and run: + +```bash +voxvera batch-import +``` + +## How URLs Work + +Each flyer has two separate URLs: +- **Tear-off link** (auto-generated): The .onion address where the flyer is hosted. +- **Content link** (user-configured): An external URL pointing to a website, video, or download. + +You do not need to manually enter the .onion address; VoxVera handles this automatically during the `serve` phase. diff --git a/docs/es/docker.md b/docs/es/docker.md new file mode 100644 index 0000000..318d35d --- /dev/null +++ b/docs/es/docker.md @@ -0,0 +1,16 @@ +# Docker Usage + +A prebuilt image containing Tor, OnionShare and the `voxvera` CLI is published to +`ghcr.io/voxvera/voxvera`. + +```bash +# pull the image +docker pull ghcr.io/voxvera/voxvera:latest + +# run voxvera quickstart with flyers stored in ./flyers +mkdir -p flyers +docker run -it --rm -v "$(pwd)/flyers:/flyers" ghcr.io/voxvera/voxvera +``` + +The container uses `/flyers` as the working directory and runs `voxvera quickstart` +by default. All generated flyer files will appear in the mounted `flyers` folder. diff --git a/docs/es/templates.md b/docs/es/templates.md new file mode 100644 index 0000000..f299c24 --- /dev/null +++ b/docs/es/templates.md @@ -0,0 +1,14 @@ +# Flyer Templates + +Pre-built flyer templates live in the `templates/` directory. Use the CLI to copy one with: + +```bash +voxvera init --template +``` + +This will create a new folder under `dist/` named `-` containing the template files. + +Available templates: + +- **blank** – minimal placeholder files, also used when extracting fields from a PDF. +- **voxvera** – example flyer showcasing the VoxVera project. diff --git a/docs/es/troubleshooting.md b/docs/es/troubleshooting.md new file mode 100644 index 0000000..e75be08 --- /dev/null +++ b/docs/es/troubleshooting.md @@ -0,0 +1,60 @@ +# Troubleshooting + +This page collects common issues encountered when hosting or accessing flyers. + +## Tor connectivity +- Ensure Tor is allowed through your firewall. On systems using `ufw` you may need to run `sudo ufw allow tor`. +- Some networks block Tor entirely. If you cannot reach onion services, try connecting over a different network or use a Tor bridge. + +## Tor port detection + +`voxvera serve` auto-detects Tor by probing common ports (9050/9150 for SOCKS, 9051/9151 for control). If detection fails -- for example when Tor runs on non-standard ports -- you can override with environment variables: + +```bash +TOR_SOCKS_PORT=19050 TOR_CONTROL_PORT=19051 voxvera serve +``` + +If no running Tor is found, the defaults (9050/9051) are used and OnionShare will attempt to connect on those ports. + +## Firewall rules +- If `voxvera serve` fails to start OnionShare, verify that outbound connections on ports 9001 and 80 are permitted. +- Corporate or university firewalls can block the hidden service ports required by Tor. + +## SELinux +- On SELinux-enabled distributions you may see `permission denied` errors when OnionShare writes to the `host` directory. +- Run `sudo chcon -Rt svirt_sandbox_file_t host` or disable SELinux enforcement for the folder. + +## OnionShare crashes +If `voxvera serve` prints "OnionShare exited unexpectedly", check the log file +`host//onionshare.log` for details. Common causes: + +- Tor is not running (`sudo systemctl start tor`) +- A port conflict with another service +- Missing `onionshare-cli` (run `voxvera check`) + +## Onion URL changed unexpectedly +The onion URL is tied to the Ed25519 keypair stored in +`host//.onionshare-session`. If this file is deleted, a new +keypair (and URL) will be generated on the next `voxvera serve`. The +`voxvera import` command preserves this file automatically, but manual +deletion of the `host/` directory will destroy it. + +## QR codes not generated +If `voxvera build` reports "No URLs configured yet", this is expected before the first `voxvera serve`. QR codes for tear-off links are generated automatically once the .onion address is known. QR codes for the content link are generated if you provided a URL during `voxvera init`. + +## Electron GUI +If `npm start` fails with `spawn voxvera ENOENT`, the `voxvera` command is not in your `PATH`. Install it with `pipx install git+https://github.com/PR0M3TH3AN/VoxVera.git` or run `./install.sh` from the repository. + +## Missing dependencies +Run `voxvera check` to verify your setup. The command checks for required +Python packages (`qrcode`, `Pillow`, `jsmin`, `htmlmin`, `pypdf`) and +external tools (`onionshare-cli`), then prints a summary of anything +missing. To install everything: + +```bash +# Recommended: use the install script (handles Tor + OnionShare too) +curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash + +# Or reinstall just the Python package +pipx install --force 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main' +``` diff --git a/docs/es/usage.md b/docs/es/usage.md new file mode 100644 index 0000000..833e23b --- /dev/null +++ b/docs/es/usage.md @@ -0,0 +1,130 @@ +# Detailed Usage + +This guide covers common CLI workflows. See `docs/docker.md` for Docker instructions and `docs/templates.md` for available flyer templates. + +## Prerequisites + +VoxVera is designed to be highly portable and requires minimal system dependencies. + +### 1. Standalone Binaries (Recommended) +You can download standalone, zero-dependency binaries for your operating system: +- **Linux:** `voxvera-linux` +- **Windows:** `voxvera-windows.exe` +- **macOS:** `voxvera-macos` + +These binaries include everything needed to run VoxVera (except `onionshare-cli`). + +### 2. One-Line Installer +Alternatively, install via our automated script: + +```bash +curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash +``` + +### 3. Manual Python Install +If you prefer to run from source: + +```bash +pipx install 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main' +sudo apt install tor onionshare-cli # Debian/Ubuntu +``` + +## Step-by-Step + +1. **Initialize:** Run `voxvera init` and follow the prompts. You will be asked to select your language first. +2. **Build:** Generate the flyer assets. Every build automatically creates a `voxvera-portable.zip` in the flyer's folder, allowing others to download the full tool directly from your flyer. + ```bash + voxvera build + ``` +3. **Serve:** Publish the flyer over Tor: + ```bash + voxvera serve + ``` + This automatically detects your Tor instance, starts OnionShare, and writes the generated .onion address into the flyer's tear-off links. + +## Language Support + +VoxVera is fully localized. You can change your language preference permanently using either the interactive selector or a direct shortcut: + +- **Interactive Selector:** `voxvera lang` +- **Direct Shortcut:** `voxvera --lang de` (sets preference to German) + +### Supported Languages: +- **English:** `en` +- **Spanish:** `es` (alias: `--idioma`) +- **German:** `de` (alias: `--sprache`) + +You can also force a specific language for a single command without changing your permanent preference: +- **English:** `voxvera --lang en check` +- **German:** `voxvera --sprache de check` +- **Spanish:** `voxvera --idioma es check` + +The generated flyers automatically detect the visitor's browser language and switch the UI text accordingly. + +## Server Management + +Manage multiple flyers and their Tor identities from a single interactive menu: + +```bash +voxvera manage +``` + +Features: +- **--- Create New Site/Flyer ---**: Start the full setup sequence. +- **Start/Stop All Sites**: Launch or shut down every flyer in your fleet at once. +- **Real-time Status**: View active `.onion` URLs and Tor bootstrapping progress indicators. +- **Individual Control**: Export specific sites to ZIP or delete them. + +## Universal Mirroring (Viral Distribution) + +To ensure VoxVera remains accessible even if central repositories are censored, every flyer acts as a mirror for the tool. + +When you host a flyer, the **"Download Tool & Source"** button on the landing page provides a `voxvera-portable.zip` containing: +- The full source code and all supported languages. +- All Python dependencies (pre-vendored). +- Cross-platform Tor binaries. + +This allows anyone who scans your flyer to become a new distributor of the VoxVera tool. + +## Export & Backup + +Back up your unique Tor identities (so your `.onion` URL never changes) or move your flyers to another machine. + +- **Export a single site**: `voxvera export ` +- **Export all sites**: `voxvera export-all` + +**Storage location:** All exports are saved to `~/voxvera-exports/` on all platforms. + +## Import & Recovery + +Restore your entire setup on a new machine by moving your ZIP files to `~/voxvera-exports/` and running: + +```bash +voxvera import-multiple +``` + +## Portability & Offline Use + +If you need to run VoxVera on a machine without internet access, you can "vendorize" the dependencies first: + +```bash +voxvera vendorize +``` + +This downloads all required Python libraries into `voxvera/vendor/`. The tool will then prioritize these local files, allowing it to run without `pip install`. + +## Batch Import (JSON) + +To bulk-generate flyers from multiple JSON configuration files, place them in the `imports/` directory and run: + +```bash +voxvera batch-import +``` + +## How URLs Work + +Each flyer has two separate URLs: +- **Tear-off link** (auto-generated): The .onion address where the flyer is hosted. +- **Content link** (user-configured): An external URL pointing to a website, video, or download. + +You do not need to manually enter the .onion address; VoxVera handles this automatically during the `serve` phase. diff --git a/docs/templates/docker.md b/docs/templates/docker.md new file mode 100644 index 0000000..318d35d --- /dev/null +++ b/docs/templates/docker.md @@ -0,0 +1,16 @@ +# Docker Usage + +A prebuilt image containing Tor, OnionShare and the `voxvera` CLI is published to +`ghcr.io/voxvera/voxvera`. + +```bash +# pull the image +docker pull ghcr.io/voxvera/voxvera:latest + +# run voxvera quickstart with flyers stored in ./flyers +mkdir -p flyers +docker run -it --rm -v "$(pwd)/flyers:/flyers" ghcr.io/voxvera/voxvera +``` + +The container uses `/flyers` as the working directory and runs `voxvera quickstart` +by default. All generated flyer files will appear in the mounted `flyers` folder. diff --git a/docs/templates/templates.md b/docs/templates/templates.md new file mode 100644 index 0000000..f299c24 --- /dev/null +++ b/docs/templates/templates.md @@ -0,0 +1,14 @@ +# Flyer Templates + +Pre-built flyer templates live in the `templates/` directory. Use the CLI to copy one with: + +```bash +voxvera init --template +``` + +This will create a new folder under `dist/` named `-` containing the template files. + +Available templates: + +- **blank** – minimal placeholder files, also used when extracting fields from a PDF. +- **voxvera** – example flyer showcasing the VoxVera project. diff --git a/docs/templates/troubleshooting.md b/docs/templates/troubleshooting.md new file mode 100644 index 0000000..e75be08 --- /dev/null +++ b/docs/templates/troubleshooting.md @@ -0,0 +1,60 @@ +# Troubleshooting + +This page collects common issues encountered when hosting or accessing flyers. + +## Tor connectivity +- Ensure Tor is allowed through your firewall. On systems using `ufw` you may need to run `sudo ufw allow tor`. +- Some networks block Tor entirely. If you cannot reach onion services, try connecting over a different network or use a Tor bridge. + +## Tor port detection + +`voxvera serve` auto-detects Tor by probing common ports (9050/9150 for SOCKS, 9051/9151 for control). If detection fails -- for example when Tor runs on non-standard ports -- you can override with environment variables: + +```bash +TOR_SOCKS_PORT=19050 TOR_CONTROL_PORT=19051 voxvera serve +``` + +If no running Tor is found, the defaults (9050/9051) are used and OnionShare will attempt to connect on those ports. + +## Firewall rules +- If `voxvera serve` fails to start OnionShare, verify that outbound connections on ports 9001 and 80 are permitted. +- Corporate or university firewalls can block the hidden service ports required by Tor. + +## SELinux +- On SELinux-enabled distributions you may see `permission denied` errors when OnionShare writes to the `host` directory. +- Run `sudo chcon -Rt svirt_sandbox_file_t host` or disable SELinux enforcement for the folder. + +## OnionShare crashes +If `voxvera serve` prints "OnionShare exited unexpectedly", check the log file +`host//onionshare.log` for details. Common causes: + +- Tor is not running (`sudo systemctl start tor`) +- A port conflict with another service +- Missing `onionshare-cli` (run `voxvera check`) + +## Onion URL changed unexpectedly +The onion URL is tied to the Ed25519 keypair stored in +`host//.onionshare-session`. If this file is deleted, a new +keypair (and URL) will be generated on the next `voxvera serve`. The +`voxvera import` command preserves this file automatically, but manual +deletion of the `host/` directory will destroy it. + +## QR codes not generated +If `voxvera build` reports "No URLs configured yet", this is expected before the first `voxvera serve`. QR codes for tear-off links are generated automatically once the .onion address is known. QR codes for the content link are generated if you provided a URL during `voxvera init`. + +## Electron GUI +If `npm start` fails with `spawn voxvera ENOENT`, the `voxvera` command is not in your `PATH`. Install it with `pipx install git+https://github.com/PR0M3TH3AN/VoxVera.git` or run `./install.sh` from the repository. + +## Missing dependencies +Run `voxvera check` to verify your setup. The command checks for required +Python packages (`qrcode`, `Pillow`, `jsmin`, `htmlmin`, `pypdf`) and +external tools (`onionshare-cli`), then prints a summary of anything +missing. To install everything: + +```bash +# Recommended: use the install script (handles Tor + OnionShare too) +curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash + +# Or reinstall just the Python package +pipx install --force 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main' +``` diff --git a/docs/templates/usage.md b/docs/templates/usage.md new file mode 100644 index 0000000..833e23b --- /dev/null +++ b/docs/templates/usage.md @@ -0,0 +1,130 @@ +# Detailed Usage + +This guide covers common CLI workflows. See `docs/docker.md` for Docker instructions and `docs/templates.md` for available flyer templates. + +## Prerequisites + +VoxVera is designed to be highly portable and requires minimal system dependencies. + +### 1. Standalone Binaries (Recommended) +You can download standalone, zero-dependency binaries for your operating system: +- **Linux:** `voxvera-linux` +- **Windows:** `voxvera-windows.exe` +- **macOS:** `voxvera-macos` + +These binaries include everything needed to run VoxVera (except `onionshare-cli`). + +### 2. One-Line Installer +Alternatively, install via our automated script: + +```bash +curl -fsSL https://raw.githubusercontent.com/PR0M3TH3AN/VoxVera/main/install.sh | bash +``` + +### 3. Manual Python Install +If you prefer to run from source: + +```bash +pipx install 'voxvera@git+https://github.com/PR0M3TH3AN/VoxVera.git@main' +sudo apt install tor onionshare-cli # Debian/Ubuntu +``` + +## Step-by-Step + +1. **Initialize:** Run `voxvera init` and follow the prompts. You will be asked to select your language first. +2. **Build:** Generate the flyer assets. Every build automatically creates a `voxvera-portable.zip` in the flyer's folder, allowing others to download the full tool directly from your flyer. + ```bash + voxvera build + ``` +3. **Serve:** Publish the flyer over Tor: + ```bash + voxvera serve + ``` + This automatically detects your Tor instance, starts OnionShare, and writes the generated .onion address into the flyer's tear-off links. + +## Language Support + +VoxVera is fully localized. You can change your language preference permanently using either the interactive selector or a direct shortcut: + +- **Interactive Selector:** `voxvera lang` +- **Direct Shortcut:** `voxvera --lang de` (sets preference to German) + +### Supported Languages: +- **English:** `en` +- **Spanish:** `es` (alias: `--idioma`) +- **German:** `de` (alias: `--sprache`) + +You can also force a specific language for a single command without changing your permanent preference: +- **English:** `voxvera --lang en check` +- **German:** `voxvera --sprache de check` +- **Spanish:** `voxvera --idioma es check` + +The generated flyers automatically detect the visitor's browser language and switch the UI text accordingly. + +## Server Management + +Manage multiple flyers and their Tor identities from a single interactive menu: + +```bash +voxvera manage +``` + +Features: +- **--- Create New Site/Flyer ---**: Start the full setup sequence. +- **Start/Stop All Sites**: Launch or shut down every flyer in your fleet at once. +- **Real-time Status**: View active `.onion` URLs and Tor bootstrapping progress indicators. +- **Individual Control**: Export specific sites to ZIP or delete them. + +## Universal Mirroring (Viral Distribution) + +To ensure VoxVera remains accessible even if central repositories are censored, every flyer acts as a mirror for the tool. + +When you host a flyer, the **"Download Tool & Source"** button on the landing page provides a `voxvera-portable.zip` containing: +- The full source code and all supported languages. +- All Python dependencies (pre-vendored). +- Cross-platform Tor binaries. + +This allows anyone who scans your flyer to become a new distributor of the VoxVera tool. + +## Export & Backup + +Back up your unique Tor identities (so your `.onion` URL never changes) or move your flyers to another machine. + +- **Export a single site**: `voxvera export ` +- **Export all sites**: `voxvera export-all` + +**Storage location:** All exports are saved to `~/voxvera-exports/` on all platforms. + +## Import & Recovery + +Restore your entire setup on a new machine by moving your ZIP files to `~/voxvera-exports/` and running: + +```bash +voxvera import-multiple +``` + +## Portability & Offline Use + +If you need to run VoxVera on a machine without internet access, you can "vendorize" the dependencies first: + +```bash +voxvera vendorize +``` + +This downloads all required Python libraries into `voxvera/vendor/`. The tool will then prioritize these local files, allowing it to run without `pip install`. + +## Batch Import (JSON) + +To bulk-generate flyers from multiple JSON configuration files, place them in the `imports/` directory and run: + +```bash +voxvera batch-import +``` + +## How URLs Work + +Each flyer has two separate URLs: +- **Tear-off link** (auto-generated): The .onion address where the flyer is hosted. +- **Content link** (user-configured): An external URL pointing to a website, video, or download. + +You do not need to manually enter the .onion address; VoxVera handles this automatically during the `serve` phase. diff --git a/voxvera/cli.py b/voxvera/cli.py index 3798ab6..f641ef2 100644 --- a/voxvera/cli.py +++ b/voxvera/cli.py @@ -652,6 +652,53 @@ def import_multiple_sites(source_dir: str = None): print("\nImport multiple complete.") +def build_docs(): + """Generate localized documentation from templates and locale data.""" + template_dir = ROOT.parent / "docs" / "templates" + if not template_dir.exists(): + print("Error: docs/templates/ not found.") + return + + # List all supported languages + locale_files = sorted(glob.glob(str(ROOT / "locales" / "*.json"))) + langs = [Path(f).stem for f in locale_files] + + for lang in langs: + print(f"Generating documentation for: {lang}") + load_locale(lang) + dest_dir = ROOT.parent / "docs" / lang + os.makedirs(dest_dir, exist_ok=True) + + # Process each template + for t_file in glob.glob(str(template_dir / "*.md")): + name = Path(t_file).name + with open(t_file, "r", encoding="utf-8") as f: + content = f.read() + + # Replace tokens: {{t('path.to.token')}} + # This regex looks for {{t('...')}} and {{t("...")}} + import re as _re + + def replace_token(match): + token_path = match.group(1) + return t(token_path) + + content = _re.sub(r"\{\{t\(['\"](.+?)['\"]\)\}\}", replace_token, content) + + # Look for localized overrides in voxvera/locales/{lang}/docs/{name} + override_path = ROOT / "locales" / lang / "docs" / name + if override_path.exists(): + with open(override_path, "r", encoding="utf-8") as f: + content = f.read() + # Process tokens in the override as well + content = _re.sub(r"\{\{t\(['\"](.+?)['\"]\)\}\}", replace_token, content) + + with open(dest_dir / name, "w", encoding="utf-8") as f: + f.write(content) + + print("Documentation build complete.") + + def vendorize(): """Download all dependencies into voxvera/vendor/ for portable use.""" vendor_dir = ROOT / "vendor" @@ -970,6 +1017,7 @@ def main(argv=None): ) sub.add_parser("check", help="Check for required external dependencies") sub.add_parser("vendorize", help="Download all dependencies into voxvera/vendor/ for portability") + sub.add_parser("build-docs", help="Generate localized documentation from templates") sub.add_parser("manage", help="Manage VoxVera servers interactively") args = parser.parse_args(argv) @@ -1056,6 +1104,8 @@ def main(argv=None): check_deps() elif args.command == "vendorize": vendorize() + elif args.command == "build-docs": + build_docs() else: parser.print_help()