sphinx-rapidoc 0.1.2

Custom Sphinx extension for embedding RapiDoc in your documentation

Sphinx-RapiDoc

A Sphinx extension that integrates RapiDoc to render beautiful, customizable, and interactive API documentation from OpenAPI/Swagger specifications.

Features

• 🚀 Quick and easy integration with Sphinx documentation
• 🎨 Customizable themes (light/dark)
• 🔄 Multiple rendering styles (read/view/focused)
• 🔒 Support for authentication
• ⚡ Interactive API testing interface
• 📱 Responsive design
• 🔍 Search functionality
• 📖 Support for OpenAPI v2.0 (Swagger) and v3.0

Installation

Install the package using pip:

pip install sphinx-rapidoc

Or install directly from GitHub for the latest version:

pip install git+https://github.com/TirthS24/sphinx_rapidoc

Quick Start

1. Add sphinx_rapidoc to your Sphinx extensions in conf.py:

   extensions = [
       # ... your other extensions
       'sphinx_rapidoc'
   ]
   

2. Create a new RST file (e.g., api.rst) with the RapiDoc directive:

   API Documentation
   ================
   
   .. rapidoc::
       :spec-url: https://api.example.com/openapi.json
       :theme: light
       :render-style: view
   

3. Include your RST file in index.rst:

   .. toctree::
      :maxdepth: 2
      :caption: Contents:
   
      api
   

4. Build your documentation:

   make html
   

Configuration Options

Directive Options

Option	Description	Default	Values
spec-url	URL to OpenAPI/Swagger specification	None	Valid URL
theme	UI theme	light	light, dark
render-style	Documentation rendering style	view	view, read, focused

Examples

Basic Usage

.. rapidoc::
    :spec-url: http://127.0.0.1:5500/src/petstore.yml
    :theme: light
    :render-style: view

Dark Theme with Read Style

.. rapidoc::
    :spec-url: http://127.0.0.1:5500/src/petstore.yml
    :theme: dark
    :render-style: read

Screenshots

Endpoint and Authentication Sections

Sample GET Request Interface

Requirements

• Python 3.9 or higher
• Sphinx 2.0 or higher
• Valid OpenAPI/Swagger specification (JSON or YAML format)
• Web browser with JavaScript enabled

Common Issues and Solutions

CORS Errors

If you encounter CORS errors, ensure that:

1. Your API specification URL is accessible from the hosted server
2. The server hosting your API specification has appropriate CORS headers
3. You're using HTTPS if your documentation is hosted on HTTPS

Specification Not Loading

• Verify that your specification URL is publicly accessible
• Check if the URL returns valid JSON/YAML in OpenAPI/Swagger format
• Ensure your specification follows OpenAPI standards

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• RapiDoc for the awesome API documentation renderer
• Sphinx for the excellent documentation generator

Support

If you encounter any issues or have questions, please:

1. Check the Common Issues section
2. Open an issue on GitHub
3. Contact the maintainers

• Tirth Shah
• Aksh Patel