diff --git a/docs/conf.py b/docs/conf.py index b5e89c2..d45e566 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -2,6 +2,7 @@ import os import sys +from datetime import datetime # Add the source directory to the Python path sys.path.insert(0, os.path.abspath("../src")) @@ -11,7 +12,7 @@ from tzst import __version__ # -- Project information ----------------------------------------------------- project = "tzst" -copyright = "2025, Xi Xu" +copyright = f"{datetime.now().year}, Xi Xu" author = "Xi Xu" release = __version__ version = __version__ diff --git a/docs/index.md b/docs/index.md index fe9cb28..a2298ae 100644 --- a/docs/index.md +++ b/docs/index.md @@ -101,74 +101,20 @@ with TzstArchive("data.tzst", "r") as archive: ## Installation -### From PyPI +For detailed installation instructions, including standalone binaries and source installation, please refer to the {doc}`quickstart` guide. ```bash +# Install from PyPI pip install tzst -``` -### From GitHub Releases - -Download platform-specific standalone executables from [GitHub Releases](https://github.com/xixu-me/tzst/releases) - no Python installation required! - -#### Supported Platforms - -| Platform | Architecture | File | -|----------|-------------|------| -| **Linux** | x86_64 | `tzst-{version}-linux-amd64.zip` | -| **Linux** | ARM64 | `tzst-{version}-linux-arm64.zip` | -| **Windows** | x64 | `tzst-{version}-windows-amd64.zip` | -| **Windows** | ARM64 | `tzst-{version}-windows-arm64.zip` | -| **macOS** | Intel | `tzst-{version}-darwin-amd64.zip` | -| **macOS** | Apple Silicon | `tzst-{version}-darwin-arm64.zip` | - -#### Installation Steps - -1. **Download** the appropriate archive for your platform from the [latest releases page](https://github.com/xixu-me/tzst/releases/latest) -2. **Extract** the archive to get the `tzst` executable (or `tzst.exe` on Windows) -3. **Move** the executable to a directory in your PATH: - - **Linux/macOS**: `sudo mv tzst /usr/local/bin/` - - **Windows**: Add the directory containing `tzst.exe` to your PATH environment variable -4. **Verify** installation: `tzst --help` - -#### Benefits of Binary Installation - -- **No Python required** - Standalone executable -- **Faster startup** - No Python interpreter overhead -- **Easy deployment** - Single file distribution -- **Consistent behavior** - Bundled dependencies - -### Using uvx (No Installation) - -Run tzst directly without installation using [uvx](https://docs.astral.sh/uv/): - -```bash -uvx tzst --help -uvx tzst a archive.tzst file1.txt file2.txt directory/ -uvx tzst x archive.tzst -``` - -Perfect for one-time usage, testing, CI/CD pipelines, and isolated environments. - -### From Source - -```bash -git clone https://github.com/xixu-me/tzst.git -cd tzst -pip install . +# Or using uv (recommended) +uv tool install tzst ``` ## Getting Started For a quick introduction, see the {doc}`quickstart` guide. For comprehensive usage examples, explore the {doc}`examples` section. -### Installation Options - -1. **PyPI Installation**: `pip install tzst` -2. **Standalone Binaries**: Download from [GitHub Releases](https://github.com/xixu-me/tzst/releases) -3. **uvx (No Installation)**: Run directly with `uvx tzst` -4. **From Source**: Clone and install from repository - ### API Documentation Complete API documentation is available in the {doc}`api/index` section, covering: diff --git a/docs/quickstart.md b/docs/quickstart.md index 1c9a8f2..2bbdae3 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -24,45 +24,52 @@ This guide will get you up and running with tzst in just a few minutes. Choose your preferred installation method: -### Option 1: PyPI +### From GitHub Releases + +Download standalone executables that don't require Python installation: + +#### Supported Platforms + +| Platform | Architecture | File | +|----------|-------------|------| +| **🐧 Linux** | x86_64 | `tzst-{version}-linux-amd64.zip` | +| **🐧 Linux** | ARM64 | `tzst-{version}-linux-arm64.zip` | +| **🪟 Windows** | x64 | `tzst-{version}-windows-amd64.zip` | +| **🪟 Windows** | ARM64 | `tzst-{version}-windows-arm64.zip` | +| **🍎 macOS** | Intel | `tzst-{version}-darwin-amd64.zip` | +| **🍎 macOS** | Apple Silicon | `tzst-{version}-darwin-arm64.zip` | + +#### 🛠️ Installation Steps + +1. **📥 Download** the appropriate archive for your platform from the [latest releases page](https://github.com/xixu-me/tzst/releases/latest) +2. **📦 Extract** the archive to get the `tzst` executable (or `tzst.exe` on Windows) +3. **📂 Move** the executable to a directory in your PATH: + - **🐧 Linux/macOS**: `sudo mv tzst /usr/local/bin/` + - **🪟 Windows**: Add the directory containing `tzst.exe` to your PATH environment variable +4. **✅ Verify** installation: `tzst --help` + +#### 🎯 Benefits of Binary Installation + +- ✅ **No Python required** - Standalone executable +- ✅ **Faster startup** - No Python interpreter overhead +- ✅ **Easy deployment** - Single file distribution +- ✅ **Consistent behavior** - Bundled dependencies + +### From PyPI + +Using pip: ```bash pip install tzst ``` -### Option 2: Standalone Binary - -Download the appropriate executable from [GitHub Releases](https://github.com/xixu-me/tzst/releases): - -| Platform | Architecture | Download | -|----------|--------------|----------| -| **Linux** | x86_64 | `tzst-{version}-linux-amd64.zip` | -| **Linux** | ARM64 | `tzst-{version}-linux-arm64.zip` | -| **Windows** | x64 | `tzst-{version}-windows-amd64.zip` | -| **Windows** | ARM64 | `tzst-{version}-windows-arm64.zip` | -| **macOS** | Intel | `tzst-{version}-darwin-amd64.zip` | -| **macOS** | Apple Silicon | `tzst-{version}-darwin-arm64.zip` | - -Extract the archive and add the executable to your PATH. - -### Option 3: Using uvx (No Installation) - -Run tzst directly without installation using [uvx](https://docs.astral.sh/uv/): +Or using uv (recommended): ```bash -uvx tzst --help -uvx tzst a archive.tzst file1.txt file2.txt directory/ -uvx tzst x archive.tzst +uv tool install tzst ``` -This option is perfect for: - -- **One-time usage** - No permanent installation needed -- **Testing** - Try tzst without committing to installation -- **CI/CD pipelines** - Use tzst in automated workflows -- **Isolated environments** - Avoid dependency conflicts - -### Option 4: From Source +### From Source ```bash git clone https://github.com/xixu-me/tzst.git @@ -70,6 +77,16 @@ cd tzst pip install . ``` +### Development Installation + +This project uses modern Python packaging standards: + +```bash +git clone https://github.com/xixu-me/tzst.git +cd tzst +pip install -e .[dev] +``` + (basic-usage)= ## Basic Usage