CLI Guide

Deploy Sphinx with Bantam CLI

Python documentation generator for professional docs

Install Bantam CLI:

npm install -g @bantamhq/cli

View on NPM: @bantamhq/cli

Quick start:

# Build your Sphinx app
make html

# Deploy it
bantam deploy _build/html

Quick Start

Install Sphinx

Install Sphinx and dependencies

pip install sphinx

Build HTML docs

Generate HTML documentation

make html

Creates _build/html directory with static files

Deploy with Bantam

Your Sphinx docs are now live!

bantam deploy _build/html

Get an instant URL like https://my-sphinx-docs-abc123.bantam.site

Framework Details

Sphinx Configuration

Configure Sphinx in conf.py:

conf.py:

# -- Project information
project = 'My Project'
copyright = '2024, Your Name'
author = 'Your Name'
release = '1.0.0'

# -- General configuration
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
    'sphinx.ext.napoleon',
    'sphinx.ext.intersphinx',
    'sphinx_rtd_theme',
]

# -- Options for HTML output
html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']
html_theme_options = {
    'logo_only': False,
    'display_version': True,
    'prev_next_buttons_location': 'bottom',
    'style_external_links': False,
    'collapse_navigation': True,
    'sticky_navigation': True,
    'navigation_depth': 4,
}

# -- Extension configuration
intersphinx_mapping = {
    'python': ('https://docs.python.org/3', None),
    'numpy': ('https://numpy.org/doc/stable/', None),
}

Sphinx can automatically generate API documentation from Python docstrings.

Auto-documentation Setup

Configure autodoc to generate API docs from code:

Setup autodoc:

# conf.py
import os
import sys
sys.path.insert(0, os.path.abspath('../src'))

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',  # Google/NumPy docstrings
    'sphinx.ext.viewcode',  # Add source code links
]

# Autodoc settings
autodoc_member_order = 'bysource'
autodoc_typehints = 'description'

Use in RST files:

API Reference
=============

.. automodule:: mypackage
   :members:
   :undoc-members:
   :show-inheritance:

.. autoclass:: mypackage.MyClass
   :members:
   :special-members: __init__

Build Output

Sphinx generates comprehensive documentation in _build/html:

index.html - Documentation homepage
_static/ - CSS, JavaScript, and images
_sources/ - Source RST files
genindex.html - General index
py-modindex.html - Python module index
search.html - Search page
searchindex.js - Search index data

Sphinx includes powerful cross-referencing and indexing capabilities.

Advanced Usage

Custom Domain

Deploy directly to your own domain

bantam deploy ./dist --domain myapp.com

Permanent Deployment

Keep your site online forever (requires login)

bantam deploy ./dist --permanent

Custom Expiry

Set how long your deployment stays online

bantam deploy ./dist --expiry-days 7

Custom Subdomain

Choose your own subdomain on bantam.site

bantam deploy ./dist --subdomain my-project

CI/CD Integration

Add Bantam to your continuous deployment pipeline:

# GitHub Actions example
- name: Deploy to Bantam
  run: |
    npm install -g @bantamhq/cli
    bantam login --token ${{ secrets.BANTAM_TOKEN }}
    bantam deploy ./dist --domain myapp.com --permanent

Troubleshooting

Common Issues & Solutions

Quick fixes for deployment challenges

01.ImportError when building docs?

Add your project to Python path:

# conf.py
import os
import sys
sys.path.insert(0, os.path.abspath('.'))
sys.path.insert(0, os.path.abspath('..'))

# For complex projects
sys.path.insert(0, os.path.abspath('../src'))

02.Theme not found?

Install the theme package:

# Read the Docs theme
pip install sphinx-rtd-theme

# Other popular themes
pip install sphinx-book-theme
pip install pydata-sphinx-theme
pip install furo

Then set in conf.py:

html_theme = 'sphinx_rtd_theme'

03.Autodoc not finding modules?

Ensure proper module structure and __init__.py files:

project/
├── docs/
│   ├── conf.py
│   └── index.rst
├── src/
│   └── mypackage/
│       ├── __init__.py
│       └── module.py
└── setup.py

Mock imports for C extensions:

# conf.py
autodoc_mock_imports = ['numpy', 'pandas', 'cv2']

04.Warning: document isn't included in any toctree?

Add documents to your table of contents:

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

   installation
   quickstart
   api/index
   tutorials/index

05.Math formulas not rendering?

Enable math support:

# conf.py
extensions = [
    'sphinx.ext.mathjax',  # or 'sphinx.ext.imgmath'
]

# In RST
:math:`\alpha = \frac{1}{2}`

.. math::
   
   \frac{\partial u}{\partial t} = \nabla^2 u