如何在Sphinx的Restructured Text中实现图片与目录并排显示

Hey there! Great question—filling that empty space next to your table of contents with an image is a fantastic way to make your Sphinx docs look more polished and professional. Let's walk through two reliable methods to pull this off, depending on the theme you're using.

Method 1: Flex Layout with Custom CSS (Works for Most Default Themes) #

This approach uses a custom container and CSS to align your image and toctree side-by-side, which plays nicely with standard themes like alabaster or sphinx_rtd_theme.

Step 1: Update Your index.rst #

Modify your existing index.rst to wrap the image and toctree in a custom container:

.. XXXXXX documentation master file, created by sphinx-quickstart on Wed Apr 11 13:59:42 2018.
You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive.

Welcome to XXXXXX's documentation!

.. container:: flex-container

   .. figure:: _static/your-project-image.png
      :width: 300px
      :alt: Your project logo or descriptive image

      Optional: Add a brief caption for your image here

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

      # Replace these with your actual documentation files
      getting_started
      api_reference
      user_guide

Step 2: Add Custom CSS #

Create a custom.css file in your Sphinx project's _static folder (create the folder if it doesn't exist) with this flex layout code:

.flex-container {
  display: flex;
  gap: 2rem; /* Adds clean space between image and toctree */
  align-items: flex-start; /* Aligns items to the top of the container */
}

/* Make it responsive for mobile devices */
@media (max-width: 768px) {
  .flex-container {
    flex-direction: column; /* Stacks items vertically on small screens */
  }
}

Step 3: Load the CSS in conf.py #

Update your conf.py to include the custom CSS file:

# Ensure this line exists (added by sphinx-quickstart by default)
html_static_path = ['_static']

# Add this line to load your custom styles
html_css_files = ['custom.css']

Method 2: Built-in Grid Layout (Sphinx Book Theme) #

If you're using the modern sphinx-book-theme (a popular choice for clean, responsive docs), you can use its built-in grid components without writing custom CSS at all.

Step 1: Install the Theme #

First, install the theme via pip:

pip install sphinx-book-theme

Step 2: Set the Theme in conf.py #

Update your conf.py to use the theme:

html_theme = 'sphinx_book_theme'

Step 3: Update index.rst with Grid Layout #

Use the grid directive to align your image and toctree seamlessly:

.. XXXXXX documentation master file, created by sphinx-quickstart on Wed Apr 11 13:59:42 2018.
You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive.

Welcome to XXXXXX's documentation!

.. grid:: 2
   :gutter: 3

   .. grid-item::

      .. figure:: _static/your-project-image.png
         :width: 100%
         :alt: Your project logo or descriptive image

         Optional: Add a brief caption here

   .. grid-item::

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

         getting_started
         api_reference
         user_guide

Key Notes #

• Image Path: Make sure your image is stored in the _static folder—Sphinx looks here for static assets by default.
• Responsiveness: Both methods include mobile-friendly behavior, so your docs will look great on phones and tablets.
• Adjust Sizing: Tweak the :width: value in the figure directive or the grid column count to match your design preferences.

内容的提问来源于stack exchange，提问作者Corsair