chore: modifications to ease into Pypi release

[vhaasteren]

PR Description: Prepare Discovery for PyPI Publication

This PR prepares the discovery package for publication on PyPI. Since we now have a Zenodo release, it makes sense to also make Discovery available on PyPI. This PR does not really do much, except that it makes minor tweaks to make the PyPI release go smooth. Once we have PyPI, it is a small step to also make it available on conda-forge.

While I could do the PyPI release myself, my reasoning is that Michele (or Pat?) should own the release, so they should do it from their account.

This PR

Includes:

• Version management via _version.py (set to 0.5.1)
• PyPI package name set to discovery-pulsar (to avoid conflicts with existing discovery package)
• GitHub Actions workflow configured to publish on releases
• Updated project metadata with correct documentation and issue tracker URLs

Changes Made

1. Version Management (src/discovery/_version.py)

   • Created _version.py file with version 0.5.1
   • Updated __init__.py to import version from _version.py

2. Package Configuration (pyproject.toml)

   • Changed package name from discovery to discovery-pulsar
   • Added Documentation URL: https://github.com/nanograv/discovery
   • Added Tracker (Issues) URL: https://github.com/nanograv/discovery/issues
   • Updated Source URL to point to nanograv/discovery repository

3. CI/CD (.github/workflows/publish.yml)

   • Added release trigger so the workflow runs automatically when a GitHub release is created

Instructions for PyPI Publication

To complete the PyPI publication process, the package owner (Michele or Pat) needs to complete the following steps:

Step 1: Create PyPI Accounts

If you don't have an account yet, register one:

1. Create a PyPI account at https://pypi.org/account/register/
2. Create a TestPyPI account at https://test.pypi.org/account/register/ (for testing)

Step 2: Generate API Tokens

1. PyPI API Token:

   • Log in to https://pypi.org
   • Go to Account Settings → API tokens
   • Click "Add API token"
   • Name it (e.g., "discovery-pulsar-publish")
   • Scope: "Entire account" (or create project-specific token after first publication)
   • Copy the token (you'll only see it once!)

2. TestPyPI API Token:

   • Log in to https://test.pypi.org
   • Follow the same process as above
   • Copy the token

Step 3: Add GitHub Secrets

1. Go to the repository: https://github.com/nanograv/discovery
2. Navigate to Settings → Secrets and variables → Actions
3. Add the following secrets:
   • PYPI_PASSWORD: Paste your PyPI API token
   • TEST_PYPI_PASSWORD: Paste your TestPyPI API token

Step 4: Test Publication on TestPyPI

Since PyPI releases are definitive, you will want to test. Therefore, test the process. It can be done in multiple ways. You can build and then upload with twine. Or you can use flit to do it all. Or, perhaps even better, integrate it in github actions (which is what I would recommend eventually). However, start with a manual upload:

1. Option A: Manual Test with Twine (Recommended for first time)

   Twine is a utility for uploading Python packages to PyPI. It's a good alternative to flit if you prefer more control over the build and upload process.

   # Install build and twine if not already installed
   pip install build twine
   
   # Clean any previous builds (optional but recommended)
   rm -rf dist/ build/ *.egg-info
   
   # Build the package (creates both source distribution and wheel)
   python -m build
   
   # This creates files in the dist/ directory:
   # - discovery-pulsar-0.5.1.tar.gz (source distribution)
   # - discovery_pulsar-0.5.1-py3-none-any.whl (wheel)
   
   # Upload to TestPyPI
   twine upload --repository testpypi dist/*

   When prompted:

   • Username: Your TestPyPI username (or __token__)
   • Password: Your TestPyPI API token (if using __token__, use the token as the password)

2. Option B: Test via GitHub Release

   • Create a test release on GitHub (e.g., v0.5.1-test)
   • The workflow will automatically attempt to publish to TestPyPI
   • Check the Actions tab to see if it succeeded

3. Verify TestPyPI Installation

   pip install -i https://test.pypi.org/simple/ discovery-pulsar

Step 5: Publish to Production PyPI

Once you've verified the TestPyPI publication works:

1. Option A: Manual Publication with Twine (Recommended)

   # Make sure you have the latest build
   python -m build
   
   # Upload to PyPI
   twine upload dist/*

   When prompted:

   • Username: Your PyPI username (or __token__)
   • Password: Your PyPI API token (if using __token__, use the token as the password)

Make sure you're uploading to production PyPI, not TestPyPI! If you have a .pypirc file, you can specify:

twine upload --repository pypi dist/*

Verification before upload:
You can check the package files before uploading:

# Check the package files
twine check dist/*

# This will validate the package and show any issues

2. Option B: Automated via GitHub Release (Recommended once it works)
   • Create a new GitHub release:
     • Go to https://github.com/nanograv/discovery/releases/new
     • Tag version: v0.5.1 (must match version in _version.py)
     • Release title: v0.5.1 (or descriptive title)
     • Description: Release notes
     • Click "Publish release"
   • The GitHub Actions workflow will automatically:
     • Build the package
     • Publish to PyPI
     • You can monitor progress in the Actions tab

Step 6: Verify Publication

1. Check PyPI: https://pypi.org/project/discovery-pulsar/
2. Test installation:

   pip install discovery-pulsar

3. Verify it works:

   import discovery as ds
   print(ds.__version__)  # Should print "0.5.1"

Future Releases

For future releases:

1. Update version in src/discovery/_version.py
2. Commit and push the change
3. Create a GitHub release with the matching tag (e.g., v0.5.2)
4. The workflow will automatically publish to PyPI

Important Notes

• The package name discovery-pulsar was chosen because discovery is already taken on PyPI. Users will install with pip install discovery-pulsar but import as import discovery.
• The version is managed in src/discovery/_version.py - update this file for each release.
• The workflow uses the microsoft/action-python reusable workflow, which handles building and publishing automatically.
• If you encounter any issues, check the GitHub Actions logs in the repository's Actions tab.

Checklist for PyPI account owner

• Create PyPI account
• Create TestPyPI account
• Generate PyPI API token
• Generate TestPyPI API token
• Add PYPI_PASSWORD secret to GitHub repository
• Add TEST_PYPI_PASSWORD secret to GitHub repository
• Test publication on TestPyPI (manual or via test release)
• Verify TestPyPI installation works
• Publish to production PyPI (manual or via GitHub release)
• Verify production PyPI installation works
• Update any documentation that references installation instructions