# Sphinx Common Issues

> Sub-skill of sphinx: Common Issues (+1).

- Skill: `vamseeachanta/sphinx-common-issues` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vamseeachanta/sphinx-common-issues`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vamseeachanta/sphinx-common-issues/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: vamseeachanta (https://skillmd.com/u/vamseeachanta)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vamseeachanta/sphinx-common-issues

---


# Common Issues (+1)

## Common Issues


#### Autodoc Cannot Find Module

```python
# conf.py - Add source to path
import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).parents[2] / 'src'))
```

#### Intersphinx Inventory Not Loading

```python
# conf.py - Use local inventory file
intersphinx_mapping = {
    'python': ('https://docs.python.org/3', 'python-objects.inv'),
}

# Download inventory manually
# curl -O https://docs.python.org/3/objects.inv
```

#### Build Warnings as Errors

```bash
# Build without -W flag for debugging
sphinx-build -b html docs/source docs/build/html

# Then fix warnings before re-enabling
sphinx-build -b html docs/source docs/build/html -W
```

#### Napoleon Not Parsing Docstrings

```python
# conf.py - Ensure napoleon is configured
napoleon_google_docstring = True
napoleon_numpy_docstring = True

# Check docstring format - must have proper indentation
def func():
    """
    Summary line.

    Args:
        param: Description.  # Note: proper indentation
    """
```

#### PDF Build Fails

```bash
# Install full LaTeX distribution
# Ubuntu
sudo apt-get install texlive-full

# macOS
brew install --cask mactex

# Check LaTeX installation
pdflatex --version
latexmk --version
```


## Debug Mode


```bash
# Verbose build
sphinx-build -b html docs/source docs/build/html -v

# Very verbose
sphinx-build -b html docs/source docs/build/html -vvv

# Show traceback on errors
sphinx-build -b html docs/source docs/build/html -T

# Keep going on errors
sphinx-build -b html docs/source docs/build/html --keep-going
```