Publish documentation

[edgarrmondragon]

Basically what's in the README plus maybe some basic auto-generated API docs.

TBD:

• Plain markdown or a framework (Sphinx, mkdocs)
• Hosting (ReadTheDocs, GitHub pages)

If you're reading this and are interested in contributing, please leave a comment!

Related

• Where are the docs?  litl/backoff#148
• Prepare for v3 release #16

[tysoncung]

I'd be happy to help set up comprehensive documentation for backoff! This is a widely-used library that deserves great docs.

Recommendations

Framework Choice: MkDocs Material

I'd suggest MkDocs with Material theme for these reasons:

Pros:

• Clean, modern UI out of the box
• Excellent search functionality
• Mobile-responsive
• Easy to maintain (pure Markdown)
• Great code highlighting
• Built-in API doc integration via mkdocstrings
• GitHub Pages deployment is trivial

Why not Sphinx:

• While Sphinx is more powerful, MkDocs is simpler for projects that are primarily about API docs + usage guides
• Faster build times
• More modern default styling
• The backoff README is already well-written markdown that can be adapted easily

Hosting: GitHub Pages

• Free and reliable
• Integrates perfectly with the repo
• Can automate deployment via GitHub Actions
• Custom domain support if desired
• URL: python-backoff.github.io/backoff/

Proposed Documentation Structure

docs/
├── index.md                    # Landing page (overview, quick install)
├── getting-started.md          # Basic usage examples
├── user-guide/
│   ├── decorators.md           # on_exception, on_predicate
│   ├── wait-strategies.md      # expo, fibo, constant, runtime
│   ├── configuration.md        # max_time, max_tries, jitter
│   ├── event-handlers.md       # on_success, on_backoff, on_giveup
│   ├── logging.md              # Logging configuration
│   └── async.md                # Async/await usage
├── advanced/
│   ├── combining-decorators.md
│   ├── runtime-config.md
│   └── custom-strategies.md
├── api/
│   └── reference.md            # Auto-generated API docs
├── examples.md                 # Real-world patterns
├── faq.md                      # Common questions
└── changelog.md                # Version history

What This Would Include

1. Migrated README content - The existing README is excellent; we'd adapt it into proper sections
2. Auto-generated API docs - Using mkdocstrings-python to pull from docstrings
3. More examples - Real-world patterns (rate limiting, API polling, database retries)
4. Comparison guide - When to use backoff vs alternatives (tenacity, etc.)
5. Troubleshooting - Common issues and solutions

Implementation Plan

Phase 1: Basic Setup

1. Create docs/ directory structure
2. Set up mkdocs.yml config
3. Migrate README content to appropriate sections
4. Configure mkdocstrings for API reference

Phase 2: Enhanced Content
5. Add more detailed examples
6. Create FAQ from common GitHub issues
7. Add comparison/alternatives section
8. Write migration guide (if needed for version updates)

Phase 3: Automation
9. GitHub Actions workflow for auto-deployment
10. Version selector (if supporting multiple versions)
11. Search optimization

GitHub Actions Workflow

Simple deploy workflow that builds and publishes on push to main:

name: Deploy Docs
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
      - run: pip install mkdocs-material mkdocstrings[python]
      - run: mkdocs gh-deploy --force

Maintenance Considerations

• Low effort: Once set up, docs stay in sync with code via mkdocstrings
• Contributors can easily update: Just edit markdown files
• Version pinning: Can document multiple versions if needed
• Examples tested: Can add doctest integration to ensure examples work

Next Steps

If this approach sounds good, I can:

1. Create a PR with the initial MkDocs setup
2. Migrate the README content into structured sections
3. Set up the GitHub Actions deployment
4. Add basic API reference generation

Let me know if you have any preferences or if there are specific sections you'd like prioritized!

[edgarrmondragon]

PRs welcome @tysoncung!

I got a draft in #33, but feel free to disregard if nothing there is useful to your approach.

[MichaelLan]

I am very interested in contributing. Although I don’t have a lot of free time because of my job, I want to help as much as I can. I’ve been looking for OSS projects to contribute to, and since I use Backoff a lot, I think it’s a great project for me to start with.

[edgarrmondragon]

I am very interested in contributing. Although I don’t have a lot of free time because of my job, I want to help as much as I can. I’ve been looking for OSS projects to contribute to, and since I use Backoff a lot, I think it’s a great project for me to start with.

@MichaelLan please log an issue if there's something missing in the project that you feel you could contribute to: documentation, tests, features, anything!