python-sphinxcustom-theme

How to point Sphinx towards a custom theme


Note: I have asked this question before but deleted it because I gave up on the project, but now I actually need to find out how.

I'm trying to make a Sphinx theme, but I can't get Sphinx to detect my theme. My folder structure looks something like this:

.
docs
   conf.py
   makefile
   make.bat
   index.md
custom_theme
   theme.toml
   layout.html

And I will point the theme in my conf.py file as such:

html_theme = 'custom_theme'

However, Sphinx will return an error with the folowing:

Theme error:
no theme named 'custom_theme' found (missing theme.toml?)
Sphinx exited with exit code: 2

How do I get Sphinx to build the Documentation with my custom theme?

Additional Context: I use Myst-Parser because I prefer markdown over reStructuredText, and I also use Sphinx Autobuild. As per the Sphinx Autobuild documentation, I ran sphinx-autobuild -a docs docs/_build/html --watch custom_theme as apprently with this command, Sphinx can detect the custom theme.

Let me know if you need more context, any and all help is appreciated. Thanks.


Solution

  • Here is how I would do it:

    1. Put the theme in a _themes folder inside the docs folder.
    2. In conf.py, add html_theme_path = ['_themes'] (in addition to html_theme = 'custom_theme' that you already have).

    Example: https://github.com/sphinx-doc/sphinx/blob/master/doc/conf.py#L36