FAQ - Frequently Asked Questions

This page answers common questions about using Sphinx documentation.

General Questions

What is Sphinx?

Sphinx is a documentation generator written in Python. It was originally created for Python documentation but supports many programming languages. It can output various formats including HTML, LaTeX, ePub, and PDF.

Why use Sphinx?

Professional output - Clean, searchable, and mobile-friendly documentation
Multiple formats - Generate HTML, PDF, ePub from the same source
Code documentation - Excellent support for API documentation
Cross-references - Easy linking between documents
Extensible - Rich ecosystem of extensions
Version control friendly - Plain text source files

What is reStructuredText?

reStructuredText (rST) is a lightweight markup language used by Sphinx. It’s more powerful than Markdown for technical documentation, supporting features like:

Cross-references
Automatic indices
Code highlighting
Admonitions (notes, warnings)
Tables of contents

Installation Issues

How do I install Sphinx?

# Basic installation
pip install sphinx

# With RTD theme
pip install sphinx sphinx-rtd-theme

# With additional tools
pip install sphinx sphinx-rtd-theme sphinx-autobuild

What Python version do I need?

Sphinx requires Python 3.8 or later. Check your version:

python --version

Common Build Errors

Build warnings about missing references

If you see warnings like WARNING: undefined label, ensure:

The referenced document exists
The label is defined correctly
Use the correct reference syntax:

:doc:`document-name`  # Reference another document
:ref:`label-name`     # Reference a label

Theme not found error

If you get Theme error: no theme named 'sphinx_rtd_theme' found:

pip install sphinx-rtd-theme

Then ensure your conf.py contains:

html_theme = 'sphinx_rtd_theme'

Writing Documentation

How do I create a table?

Simple table:

========  ========  ========
Header 1  Header 2  Header 3
========  ========  ========
Row 1     Data      Data
Row 2     Data      Data
========  ========  ========

Result:

Header 1	Header 2	Header 3
Row 1	Data	Data
Row 2	Data	Data

How do I add images?

.. image:: path/to/image.png
   :width: 400
   :alt: Alternative text
   :align: center

.. figure:: path/to/figure.png
   :scale: 50 %
   :alt: Alternative text

   This is the figure caption.

How do I create admonitions?

.. note::
   This is a note.

.. warning::
   This is a warning.

.. tip::
   This is a tip.

.. important::
   This is important.

Results in:

Note

This is a note.

Warning

This is a warning.

Advanced Topics

How do I use autodoc?

Enable in conf.py:

extensions = ['sphinx.ext.autodoc']

Document your Python code:

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

How do I customize the theme?

In conf.py:

html_theme_options = {
    'navigation_depth': 4,
    'collapse_navigation': False,
    'sticky_navigation': True,
    'includehidden': True,
    'titles_only': False
}

How do I add custom CSS?

Create _static/custom.css
Add to conf.py:

html_static_path = ['_static']
html_css_files = ['custom.css']

Deployment

How do I host on GitHub Pages?

Build your docs:

make html

Create a .nojekyll file in the output directory
Push to a gh-pages branch
Enable GitHub Pages in repository settings

How do I host on Read the Docs?

Create account at readthedocs.org
Import your GitHub/GitLab repository
RTD will automatically build on each commit

Best Practices

Documentation Structure

Recommended structure:

docs/
├── conf.py
├── index.rst
├── getting-started.rst
├── user-guide/
│   ├── index.rst
│   └── ...
├── api-reference/
│   ├── index.rst
│   └── ...
└── _static/
    └── custom.css

Version Control

Add to .gitignore:

_build/
*.pyc
.DS_Store
Thumbs.db

Writing Style

Use clear, concise language
Include code examples
Add cross-references
Use consistent formatting
Include a table of contents
Test all code examples

Troubleshooting

Documentation not updating

Clear the build directory:

make clean
make html

Check for syntax errors in rST files
Verify all referenced files exist

Search not working

Ensure JavaScript is enabled in your browser. For local builds, you may need to serve files through a web server:

python -m http.server -d _build/html

Links not working

Use :doc: for internal documents
Use :ref: for labels
Check file paths are correct
Ensure target documents are in the toctree

Getting Help

Where can I find more information?

How do I report issues?

For Sphinx issues: * GitHub: https://github.com/sphinx-doc/sphinx/issues

For theme issues: * RTD Theme: https://github.com/readthedocs/sphinx_rtd_theme/issues