API Docs Build Troubleshooting¶
Last Updated: 2026-07-11 Version: v0.2.0
**Last Updated: 2026-06-22
Common Pitfalls & Fixes
Overview¶
This guide addresses common issues encountered when building API documentation with pdoc3 and provides solutions.
Common Issues¶
1. ImportError on optional dependencies¶
Symptom:
ImportError: No module named 'wandb'
ImportError: No module named 'tensorboard'
ImportError: cannot import name 'functional' from 'torch.nn'
```text
**Cause**: The module being documented imports optional dependencies that aren't installed.
**Solutions**:
**Option A**: Add to allowlist in validator
```bash
python tools/validate_api_docs.py \
--package codex_ml \
--allow-optional "wandb" "tensorboard" "torch" "transformers" "peft" "accelerate"
```text
**Option B**: Gate imports in source code
```python
# In module that uses optional dependencies
try:
import wandb
WANDB_AVAILABLE = True
except ImportError:
WANDB_AVAILABLE = False
wandb = None
# Use conditional imports
if WANDB_AVAILABLE:
# wandb code here
pass
```text
**Option C**: Install optional dependencies
```bash
pip install -e ".[all]" # Install all optional dependencies
# or
pip install wandb tensorboard # Install specific ones
```text
---
## 2. pdoc unavailable offline
**Symptom**:
```json
{
"build_report": {
"built": false,
"notes": "pdoc unavailable: ModuleNotFoundError: No module named 'pdoc'"
}
}
```text
**Solution**:
```bash
# Install pdoc3
pip install pdoc3
# Or let the build script install it automatically
python tools/build_api_docs.py
```text
**Offline workaround**: The validator will print a "skipped" note and exit gracefully.
---
## 3. Missing package on PYTHONPATH
**Symptom**:
```text
ModuleNotFoundError: No module named 'codex'
ModuleNotFoundError: No module named 'codex_ml'
```text
**Cause**: Python can't find the package modules.
**Solutions**:
**Option A**: Install in editable mode (recommended)
```bash
pip install -e .
```text
**Option B**: Set PYTHONPATH manually
```bash
export PYTHONPATH=/path/to/repo/src:$PYTHONPATH
python tools/build_api_docs.py
```text
**Option C**: The build script automatically adds `src/` to path (already handled)
---
### 4. No HTML outputs after build
**Symptom**:
```json
{
"build_report": {
"built": true,
"file_count": 0
}
}
```text
**Causes & Fixes**:
1. **Package has no public modules**
- Verify package `__init__.py` exposes modules
- Check that modules have public classes/functions
2. **Wrong package name**
```bash
# Check available packages
python -c "import codex.cli; print(codex.cli.__file__)"
```
3. **Clear artifacts and retry**
```bash
rm -rf artifacts/docs/api/*
python tools/build_api_docs.py
```
---
### 5. Modules not discovered during import scan
**Symptom**: Expected modules don't appear in documentation
**Causes & Fixes**:
1. **Missing `__init__.py`**
- Ensure all package directories have `__init__.py`
2. **Namespace package configuration**
```python
# In __init__.py
from . import submodule # Explicit import
- Dynamic imports not discovered
- pdoc scans static imports; ensure modules are imported in
__init__.py
6. Local torch directory conflicts¶
Symptom:
ImportError: cannot import name 'functional' from 'torch.nn' (/path/to/torch/nn/__init__.py)
```text
**Cause**: A local `torch/` directory shadows the real PyTorch package.
**Solution**:
```bash
# Rename or remove local torch directory
mv torch torch_local
# Or ensure it's not in PYTHONPATH
```text
---
## 7. Deprecation warnings in docs
**Symptom**:
```text
DeprecationWarning: codex_ml.interfaces.tokenizer_hf is deprecated
```text
**Fix**: These are informational and don't block the build. To suppress:
```bash
python -W ignore::DeprecationWarning tools/build_api_docs.py
```text
---
### 8. Permission denied writing to output directory
**Symptom**:
```text
PermissionError: [Errno 13] Permission denied: 'artifacts/docs/api'
```text
**Solution**:
```bash
# Ensure directory is writable
chmod -R u+w artifacts/docs/
# Or use a different output directory
python tools/build_api_docs.py --output-dir /tmp/api_docs
```text
---
## 9. Build succeeds but pages are blank
**Symptom**: HTML files generated but have no content
**Causes & Fixes**:
1. **Missing docstrings**
```python
# Add module-level docstring
"""
Module description here.
"""
def my_function():
"""Function description."""
pass
- Private modules (starting with
_) - pdoc3 skips private modules by default
- Rename modules to not start with underscore if they should be public
10. Slow build performance¶
Symptom: Build takes a long time
Solutions:
-
Build specific packages only
-
Skip optional modules
-
Use incremental builds (not implemented yet)
Diagnostic Commands¶
Check package importability¶
```bash
Test if package can be imported¶
PYTHONPATH=src python -c "import codex.cli; print(' codex.cli importable')" PYTHONPATH=src python -c "import codex_ml; print(' codex_ml importable')" ```text
List package modules¶
```bash
See what modules are discovered¶
python -c " import pkgutil import codex.cli for mod in pkgutil.walk_packages(codex.cli.path, prefix='codex.cli.'): print(mod.name) " ```text
Check pdoc installation¶
bash
pdoc --version
python -c "import pdoc; print(pdoc.__version__)"text
Verify build output¶
```bash
Check what was generated¶
find artifacts/docs/api -name "*.html" | head -20 ```text
Escalation¶
If issues persist after trying these solutions:
-
Gather information:
bash python tools/validate_api_docs.py \ --package codex.cli \ --out artifacts/docs/api \ --summary > validation_report.json -
Include environment details:
bash python --version pip list | grep -E "pdoc|sphinx" echo $PYTHONPATH -
Attach the JSON report and command used to reproduce
-
Open an issue on GitHub with
[docs]tag
Best Practices¶
For Module Authors¶
- Add docstrings to all public modules, classes, and functions
- Gate optional imports with try/except
- Document parameters and return types in docstrings
- Keep import dependencies minimal for documentation modules
For Documentation Builders¶
- Start with small packages (like
codex.cli) before attempting full builds - Use
--skip-optionalfor minimal environments - Check import errors before debugging pdoc issues
- Keep output directory clean between builds
Related Documentation¶
Reference¶
| Issue | Quick Fix |
|---|---|
| Import error on optional dep | Add to --allow-optional list |
| Missing PYTHONPATH | Run pip install -e . |
| No HTML output | Check package name and module structure |
| pdoc not found | Run pip install pdoc3 |
| Stale artifacts | rm -rf artifacts/docs/api/* |
| Slow build | Use --skip-optional or build smaller packages |