Sphinx Python Highlighting Looks Half-Colored? Switch Pygments Styles for IDE-Like Results

Learn why Sphinx shows partial Python highlighting and how Pygments styles control colors. List styles, pick one to match your IDE, and boost readability.

Code highlighting in Sphinx not matching what you see in your editor can be surprising, especially when pieces of a Python snippet stay uncolored. If your documentation uses the default look and your expectation is a VS Code–like palette, the root of the mismatch is almost always the chosen style rather than an error in your setup.

Problem setup

You have a Python code-block in Sphinx and notice that only parts of it are highlighted. The configuration uses the default style. The snippet looks like this:

import logging as logsys
logsys.getLogger('mymodule').setLevel(logsys.INFO)

In the rendered page, function calls and some names remain uncolored, while keywords and strings might be highlighted. This feels incomplete if you expect a broader spectrum of token colors similar to your IDE.

What is actually happening

The visual result depends on the active Pygments style. Styles define which token types get colors and which stay neutral. Many built-in styles deliberately keep call sites and certain names plain. This is a design choice of the theme, not a failure of the highlighter. As noted in the Pygments styles reference, most styles do not color functions at call sites in their examples.

Most styles do not color functions at call sites (Math.fib in those examples).

If “partial highlighting” looks wrong to you, you likely just need a different style that colors more token categories to match your taste.

Solution

First, list which styles are available in your environment so you can try them. Run this small helper:

from pygments.styles import get_all_styles as enumerate_styles

print(list(enumerate_styles()))

This will print the names you can plug into your Sphinx configuration. The next step is simple trial and error: pick a candidate style from that list, build the docs, and decide if you like the result. If none of the built-in options satisfies you, install a plug-in that provides a style closer to your preference.

Why this matters

Documentation is part of your developer experience. Readable code samples reduce cognitive load, speed up scanning, and make examples less error-prone to copy. When highlighting matches how you think about code, it’s easier to spot what matters in a snippet—whether that’s function calls, namespaced access, or log levels. Choosing the right style is a small tweak with a high payoff.

Takeaways

If Python snippets in Sphinx look “half-colored,” it’s not necessarily a bug. The effect comes from the chosen Pygments style, and many default styles intentionally leave call sites and some names uncolored. Enumerate available styles programmatically, try a few, and switch to the one that fits your visual expectations. If nothing clicks, look for an external style plug-in that matches your workflow.