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? ^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash # 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: .. code-block:: bash python --version Common Build Errors ------------------- Build warnings about missing references ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If you see warnings like ``WARNING: undefined label``, ensure: 1. The referenced document exists 2. The label is defined correctly 3. Use the correct reference syntax: .. code-block:: rst :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``: .. code-block:: bash pip install sphinx-rtd-theme Then ensure your ``conf.py`` contains: .. code-block:: python html_theme = 'sphinx_rtd_theme' Writing Documentation --------------------- How do I create a table? ^^^^^^^^^^^^^^^^^^^^^^^^^ Simple table: .. code-block:: rst ======== ======== ======== 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? ^^^^^^^^^^^^^^^^^^^^ .. code-block:: rst .. 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? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: rst .. 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? ^^^^^^^^^^^^^^^^^^^^^^ 1. Enable in ``conf.py``: .. code-block:: python extensions = ['sphinx.ext.autodoc'] 2. Document your Python code: .. code-block:: rst .. automodule:: mymodule :members: :undoc-members: :show-inheritance: How do I customize the theme? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In ``conf.py``: .. code-block:: python html_theme_options = { 'navigation_depth': 4, 'collapse_navigation': False, 'sticky_navigation': True, 'includehidden': True, 'titles_only': False } How do I add custom CSS? ^^^^^^^^^^^^^^^^^^^^^^^^^ 1. Create ``_static/custom.css`` 2. Add to ``conf.py``: .. code-block:: python html_static_path = ['_static'] html_css_files = ['custom.css'] Deployment ---------- How do I host on GitHub Pages? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. Build your docs: .. code-block:: bash make html 2. Create a ``.nojekyll`` file in the output directory 3. Push to a ``gh-pages`` branch 4. Enable GitHub Pages in repository settings How do I host on Read the Docs? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. Create account at readthedocs.org 2. Import your GitHub/GitLab repository 3. RTD will automatically build on each commit Best Practices -------------- Documentation Structure ^^^^^^^^^^^^^^^^^^^^^^^ Recommended structure: .. code-block:: text docs/ ├── conf.py ├── index.rst ├── getting-started.rst ├── user-guide/ │ ├── index.rst │ └── ... ├── api-reference/ │ ├── index.rst │ └── ... └── _static/ └── custom.css Version Control ^^^^^^^^^^^^^^^ Add to ``.gitignore``: .. code-block:: text _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 ^^^^^^^^^^^^^^^^^^^^^^^^^^ 1. Clear the build directory: .. code-block:: bash make clean make html 2. Check for syntax errors in rST files 3. 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: .. code-block:: bash 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? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * `Official Sphinx Documentation `_ * `reStructuredText Primer `_ * `Read the Docs Documentation `_ * `Sphinx Users Mailing List `_ 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 See Also -------- * :doc:`getting-started` - Initial setup guide * :doc:`api-reference` - API documentation examples * :doc:`examples` - Code examples and snippets