Skip to content

PUBLISHING.md

Latest commit

 

History

History
187 lines (131 loc) · 3.94 KB

PUBLISHING.md

File metadata and controls

187 lines (131 loc) · 3.94 KB

Publishing Guide for md2doc

This guide explains how to publish the md2doc package to PyPI.

Prerequisites

  1. PyPI Account: Create an account on PyPI
  2. TestPyPI Account: Create an account on TestPyPI for testing
  3. API Token: Generate an API token from your PyPI account settings

Setup

1. Install Publishing Tools

# Install build tools
uv pip install build twine

# Or install globally
pip install build twine

2. Configure PyPI Credentials

You have several options for authentication with uv publish:

Option A: Environment Variables (Recommended)

Set environment variables for authentication:

# For PyPI
export UV_PUBLISH_TOKEN="your-pypi-token-here"
export UV_PUBLISH_URL="https://upload.pypi.org/legacy/"

# For TestPyPI
export UV_PUBLISH_TOKEN="your-testpypi-token-here"
export UV_PUBLISH_URL="https://test.pypi.org/legacy/"

Option B: Command Line Arguments

Pass credentials directly in the command:

# For PyPI
uv publish -t "your-pypi-token-here" --publish-url "https://upload.pypi.org/legacy/"

# For TestPyPI
uv publish -t "your-testpypi-token-here" --publish-url "https://test.pypi.org/legacy/"

Option C: Traditional ~/.pypirc (for twine)

If you prefer using twine, create a ~/.pypirc file:

[distutils]
index-servers =
    pypi
    testpypi

[pypi]
repository = https://upload.pypi.org/legacy/
username = __token__
password = your-pypi-token-here

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = your-testpypi-token-here

Publishing Process

Option 1: Using the Automated Script

# Make script executable (if not already)
chmod +x publish.sh

# Run the publish script
./publish.sh

Option 2: Manual Publishing

Step 1: Build the Package

# Clean previous builds
rm -rf dist/ build/ *.egg-info/

# Build the package
uv build

Step 2: Test on TestPyPI (Recommended)

# Upload to TestPyPI using environment variables
export UV_PUBLISH_TOKEN="your-testpypi-token-here"
export UV_PUBLISH_URL="https://test.pypi.org/legacy/"
uv publish

# Or using command line arguments
uv publish -t "your-testpypi-token-here" --publish-url "https://test.pypi.org/legacy/"

# Test installation
uvx md2doc --index-url https://test.pypi.org/simple/

Step 3: Publish to PyPI

# Upload to PyPI using environment variables
export UV_PUBLISH_TOKEN="your-pypi-token-here"
export UV_PUBLISH_URL="https://upload.pypi.org/legacy/"
uv publish

# Or using command line arguments
uv publish -t "your-pypi-token-here" --publish-url "https://upload.pypi.org/legacy/"

Version Management

To update the version:

  1. Edit pyproject.toml:

    [project]
version = "0.1.1"  # Increment version

  2. Update md2doc/__init__.py:

    __version__ = "0.1.1"

  3. Build and publish:

    ./publish.sh

Verification

After publishing, verify the installation:

# Test installation
uvx md2doc

# Or install and test
uv pip install md2doc
python -c "import md2doc; print(md2doc.__version__)"

Troubleshooting

Common Issues

  1. Authentication Error: Check your ~/.pypirc file and API tokens
  2. Version Already Exists: Increment the version number in pyproject.toml
  3. Build Errors: Ensure all dependencies are correctly specified

Testing Locally

# Test the package locally before publishing
uv pip install -e .
python test_package.py

Package Information

Support

If you encounter issues during publishing:

  1. Check the PyPI documentation
  2. Verify your package structure with python -m build --sdist --wheel
  3. Test with TestPyPI first