Custom color scheme, design, and logo of readthedocs page

This very short tutorial documents how I gave the pylanetary project’s readthedocs page a custom logo and layout. The logo was designed by Jacob Waliszewski at jwdesignco, so massive shout-out to him. It looks fantastic!

Pylanetary uses a pyproject.toml file to handle its packaging in a way that’s compatible with Python 3.12, and relies on sphinx-pyproject so that most of the options that would normally go in sphinx’s conf.py go inside pyproject.toml under [tool.sphinx-pyproject]. Your mileage may vary if you are using some other setup.

Add a logo in the top-left corner

This was dead simple, since sphinx has an explicit option for this. Simply:

• Put a .png of the logo into the docs/ folder, NOT docs/_static. The file will be copied to static during the build.
• Ensure the lines html_static_path = ['_static'] and html_logo = "logo.png" are both in pyproject.toml under [tool.sphinx-pyproject]
• To test, just make clean html from within the docs folder as usual.

Change the layout

I didn’t like any of the native sphinx site designs - either they look super outdated, or too many other packages already use it. Thankfully, the open-source community has created tons of options, which are compiled here. I chose Furo. It was super easy to implement, I simply ran pip install furo, added furo to my docs/requirements.txt file, and then set html_theme = "furo".

Change the color scheme

This is done by setting the html_theme_options for sphinx. The allowed options appear to depend a bit on the choice of theme. For Furo, this was the syntax: html_theme_options = {"light_css_variables" = {"color-brand-primary" = "#002f87"}, "dark_css_variables" = {"color-brand-primary" = "#00a7e1"}} I am ashamed to admit how long it took me to figure out the syntax for this dictionary in pyproject.toml. it seemed to need all of it on one line. Thanks again to Jacob for sending me the hex colors so we could have a consistent color scheme.

Sphinx Copy Button

I browsed the Recommendations page given in the Furo docs, and ended up adding just one: the code copier button. This integrated easily into both in-line code blocks in the .rst files and the tutorials written in Jupyter notebook and generated by nbsphinx. It was also super easy to implement, I simply ran pip install sphinx-copybutton, added "sphinx_copybutton" to the list of sphinx extensions, and added it to my docs/requirements.txt file.

Testing the build

Testing the docs build as part of the integration tests that run on GitHub upon submitting a PR is as simple as clicking an option box in the project’s readthedocs settings. I learned this as part of this project. When you do so, the full build will be available from the project’s readthedocs build page, e.g., https://readthedocs.org/projects/pylanetary/builds/.