diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..5a71a4b8 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,71 @@ +name: Documentation + +on: + push: + branches: + - main + paths: + - 'docs/**' + - 'runpod/**' + - '.github/workflows/docs.yml' + pull_request: + branches: + - main + paths: + - 'docs/**' + - 'runpod/**' + - '.github/workflows/docs.yml' + # Allow manual trigger + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + cache: 'pip' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -r docs/requirements.txt + pip install -e . + + - name: Build documentation + run: | + cd docs + make clean html + # Create .nojekyll file to prevent GitHub Pages from ignoring files that begin with an underscore + touch build/html/.nojekyll + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: docs/build/html + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + if: github.ref == 'refs/heads/main' + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..92f501f1 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..a8d7f5db --- /dev/null +++ b/docs/README.md @@ -0,0 +1,134 @@ +# RunPod Python SDK Documentation Guide + +This directory contains the Sphinx documentation for the RunPod Python SDK. This guide will help you set up, build, and contribute to the documentation. + +## Prerequisites + +Before you begin, ensure you have Python 3.7+ installed. You'll also need to install the documentation dependencies: + +```bash +pip install -r requirements.txt +``` + +## Building the Documentation + +### Quick Start + +To build the documentation: + +1. Navigate to the docs directory: + ```bash + cd docs + ``` + +2. Build the HTML documentation: + ```bash + make html + ``` + +The built documentation will be available in `build/html/`. Open `build/html/index.html` in your web browser to view it. + +### Other Build Options + +- Clean and rebuild: + ```bash + make clean html + ``` + +- Build specific formats: + ```bash + make latexpdf # Build PDF documentation + make epub # Build EPUB documentation + ``` + +## Documentation Structure + +``` +docs/ +├── Makefile # Build system +├── requirements.txt # Documentation dependencies +├── source/ +│ ├── conf.py # Sphinx configuration +│ ├── index.rst # Documentation homepage +│ ├── installation.rst # Installation guide +│ ├── quickstart.rst # Getting started guide +│ ├── api/ # API reference +│ │ ├── index.rst # API overview +│ │ ├── error.rst # Error handling +│ │ ├── http_client.rst # HTTP client +│ │ └── serverless/ # Serverless components +│ │ ├── core.rst # Core functionality +│ │ ├── worker.rst # Worker implementation +│ │ └── modules/ # Additional modules +│ └── _static/ # Static files (images, custom CSS) +└── build/ # Built documentation + └── html/ # HTML output +``` + +## Common Issues and Solutions + +### Missing API Key Warning +If you see warnings about missing API keys during the build: +``` +ValueError: No authentication credentials found. Please set RUNPOD_AI_API_KEY +``` +This is expected in a development environment and won't affect the documentation quality. The API key is only required for running the actual SDK. + +### Import Warnings +If you encounter import-related warnings, ensure you have: +1. Installed the package in development mode: `pip install -e ..` +2. Installed all required dependencies: `pip install -r requirements.txt` + +### Title Underline Warnings +Warnings about title underlines being too short are formatting issues. Ensure your RST files use consistent title decoration: +```rst +Section Title +============ + +Subsection Title +--------------- + +Sub-subsection Title +~~~~~~~~~~~~~~~~~~~ +``` + +## Contributing to Documentation + +### Adding New Pages +1. Create a new `.rst` file in the appropriate directory under `source/` +2. Add the file to the relevant `toctree` directive in `index.rst` or parent page +3. Use proper RST syntax for headings, code blocks, and cross-references + +### Style Guidelines +1. Use Google-style docstrings in Python code +2. Keep line length under 100 characters +3. Use proper RST directives for: + - Code examples: `.. code-block:: python` + - Notes and warnings: `.. note::`, `.. warning::` + - Cross-references: `:ref:`, `:class:`, `:meth:` + +### Building for Production +For production builds: +1. Clean previous builds: `make clean` +2. Run spell check: `make spelling` +3. Build HTML: `make html` +4. Check for broken links: `make linkcheck` + +## Maintenance + +### Regular Updates +1. Keep dependencies up to date in `requirements.txt` +2. Review and update code examples +3. Verify cross-references and links +4. Update version numbers in `conf.py` + +### Version Control +1. Document significant changes in changelog +2. Tag documentation versions to match SDK releases +3. Keep main branch documentation in sync with latest stable release + +## Additional Resources + +- [Sphinx Documentation](https://www.sphinx-doc.org/) +- [reStructuredText Guide](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) +- [RunPod API Reference](https://docs.runpod.io/reference) diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..60e1fec6 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,13 @@ +sphinx>=8.1.3 +sphinx-copybutton>=0.5.2 +furo>=2024.8.6 +myst-parser>=4.0.0 +sphinx-basic-ng>=1.0.0b2 +sphinx-rtd-theme>=2.0.0 +sphinx-autodoc-typehints>=1.25.2 +sphinx-design>=0.5.0 +sphinx-notfound-page>=1.0.0 +sphinx-sitemap>=2.5.1 +sphinx-togglebutton>=0.3.2 +sphinx-tabs>=3.4.5 +sphinx-autobuild>=2024.2.0